Aller au contenu principal

Publication de Docusaurus i18n

· 4 minutes de lecture
Sébastien Lorber
Sébastien Lorber
Mainteneur de Docusaurus, rédacteur de This Week In React

Today, we officially release Docusaurus 2 i18n (internationalization), as part of 2.0.0-alpha.71.

Docusaurus 2 has now reached full feature parity with Docusaurus 1. 🎉 And soon, after a few additional infrastructure updates and a bit more testing, the first Docusaurus 2 beta will be released.

We went the extra mile, and the new i18n support is even better than in Docusaurus 1.

In this post, we will present you the translation workflow, explain some design decisions and showcase early adopter sites that just went live: Jest, Redwood, and Datagit.

We also dogfood the i18n support on the Docusaurus 2 site itself, and this post is already available in English and French!

Traduisez votre site​

You can translate a Docusaurus site in 3 simple steps:

  1. Configurez : déclarez la locale par défaut et les locales alternatives dans docusaurus.config.js
  2. Translate: put the translation files at the correct filesystem location
  3. Déployez : construisez et déployez votre site en utilisant une stratégie basée sur un ou plusieurs domaines

The i18n support is very flexible and based on the filesystem.

The i18n tutorial is the best way to get started, and we provide help to use Git or Crowdin.

Décisions de conception​

Les objectifs du système Docusaurus i18n sont :

  • Simple: just put the translated files in the correct filesystem location
  • Flux de traduction flexibles : basés sur Git (monorepo, forks ou submodules), logiciel SaaS, FTP
  • Options de déploiement flexibles : domaines uniques, multiples ou hybrides
  • Modulaire : permet aux auteurs de plugins de fournir une prise en charge i18n
  • Low-overhead runtime: documentation is mostly static and does not require a heavy JS library or polyfills
  • Délais de construction modulables : permet la construction et le déploiement indépendant de sites localisés
  • Localiser les ressources : une image de votre site peut contenir du texte qui doit être traduit
  • Pas de couplage : aucune obligation d'utiliser un SaaS, mais les intégrations sont possibles
  • Easy to use with Crowdin: multiple Docusaurus 1 sites use Crowdin, and should be able to migrate to v2
  • Bon SEO par défauts : nous définissons pour vous des entêtes SEO utiles comme hreflang
  • Prise en charge RTL : les locales avec lecture de droite à gauche (Arabe, Hébreu, etc.) sont pris en charge et faciles à implémenter
  • Traductions par défaut : les libellés du thème classic sont traduites pour vous dans de nombreuses langues

Galerie​

We worked with a few volunteers to dogfood the i18n support before releasing it.

Jest : Mise à niveau de Docusaurus​

We have made it possible to upgrade a translated Docusaurus 1 site to Docusaurus 2.

Jest, using Docusaurus 1 and Crowdin was one of those sites.

The Docusaurus 2 migration was successful and the new site is now deployed in production (announcement post).

Jest's website front page in Japanese

Redwood : adoption de Docusaurus​

Redwood is a React full-stack Jamstack framework.

They were looking for a solution to create an internationalized learning platform, and became early adopters of Docusaurus 2 i18n for learn.redwoodjs.com, using Crowdin to get it translated to French.

Redwood's doc page in French

Datagit : utilisation du support LTR​

The i18n system should work with any language, including Right-to-Left languages.

Datagit.ir is using Farsi, and a simple configuration option is able to flip the Docusaurus theme to add the required Right-to-Left support.

Datagit's website in Persian, a right-to-left language. The sidebar appears on the right of the window and the TOC appears on the left.

Conclusion​

Nous espérons sincèrement que vous adopterez et apprécierez le nouveau soutien de l’i18n.

Cette fonctionnalité n'a pas été facile, et nous voudrions remercier tous ceux qui ont été impliqués dans ce voyage :

  • Alexey for his help to make the i18n support exhaustive and even better than v1
  • Simen for volunteering and supporting the Jest migration
  • Claire for adopting Docusaurus 2 on the new Redwood platform and providing many feedbacks
  • Massoud for reviewing my work on LTR and adopting it on Datagit
  • Crowdin for their support and willingness to improve their translation SaaS
  • La communauté Docusaurus pour leur patience, et et les nombreux commentaires utiles sur GitHub

Merci d'avoir pris le temps de lire !

🙏 And please, add your brand new i18n sites to our showcase page. We accept any all polished Docusaurus site here, and we are working on a redesign allowing you to filter sites by features.