Aujourd'hui, nous publions officiellement le support i18n de Docusaurus 2 (internationalisation), dans la version 2.0.0-alpha.71.
Docusaurus 2 a maintenant atteint la parité de la fonctionnalité complète avec Docusaurus 1. 🎉 Et bientôt, après quelques mises à jour d'infrastructure supplémentaires et un peu plus de tests, la première beta de Docusaurus 2 sera publiée.
Nous avons fait du zèle, et le nouveau support i18n est encore meilleur que celui de Docusaurus 1.
Dans ce post, nous vous présenterons le workflow de traduction, expliquerons quelques décisions de conception et mettrons en avant les premières utilisations qui viennent d'être mis en ligne : Jest, Redwoodet Datagit.
Nous utilisons notre propre solution sur le site Docusaurus 2 lui-même, et cet article est déjà disponible en anglais et français !
Traduisez votre site
Vous pouvez traduire un site Docusaurus en 3 étapes simples :
- Configurez : déclarez la locale par défaut et les locales alternatives dans
docusaurus.config.js - Traduisez : mettez les fichiers de traduction au bon emplacement du système de fichiers
- Déployez : construisez et déployez votre site en utilisant une stratégie basée sur un ou plusieurs domaines
Le support i18n est très flexible et basé sur le système de fichiers.
Le tutoriel i18n est le meilleur moyen de commencer, et nous fournissons de l'aide pour utiliser Git ou Crowdin.
Décisions de conception
Les objectifs du système Docusaurus i18n sont :
- Simple : mettez simplement les fichiers traduits au bon emplacement du système de fichiers
- Flexible : utilisez Git (monorepo, forks, ou sous-modules), un SaaS ou un FTP
- Déploiement : domaine unique, plusieurs domaines ou hybride
- Modulaire : permet aux auteurs de plugins de fournir un support i18n
- Runtime léger : la documentation est principalement statique et ne nécessite pas de librairie JS ou de polyfills lourds
- Temps de build scalables : 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
- Facile à utiliser avec Crowdin : plusieurs sites Docusaurus 1 utilisent Crowdin, et devraient être en mesure de migrer vers v2
- Bon SEO par défaut : nous définissons des en-têtes SEO utiles comme
hreflangpour vous - Prise en charge RTL : les locales avec lecture de droite à gauche (arabe, hébreu, etc.) sont prises 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
Nous avons travaillé avec quelques bénévoles pour tester le support i18n avant de le publier.
Jest : Mise à niveau de Docusaurus
Nous avons rendu possible la mise à jour d'un site Docusaurus 1 traduit vers Docusaurus 2.
Jest, utilisant Docusaurus 1 et Crowdin, était l'un de ces sites.
La migration de Docusaurus 2 a été un succès et le nouveau site est maintenant déployé en production (post d'annonce).
Redwood : adoption de Docusaurus
Redwood est un framework ReactJamstack full-stack.
Ils cherchaient une solution pour créer une plateforme d'apprentissage internationalisée, et ont adopté Docusaurus 2 i18n pour learn.redwoodjs.com, en utilisant Crowdin pour le faire traduire en français.
Datagit : utilisation du support LTR
Le système i18n devrait pouvoir fonctionner avec n'importe quelle langue, y compris les langues avec lecture de droite à gauche.
Datagit.ir utilise Farsi, et une simple option de configuration est en mesure de retourner le thème Docusaurus pour ajouter le support requis de droite à gauche.
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 pour son aide à rendre le support i18n exhaustif et encore mieux que v1
- Simen pour se porter volontaire et soutenir la migration de Jest
- Claire pour adopter Docusaurus 2 sur la nouvelle plate-forme Redwood et fournir de nombreux retours
- Massoud pour avoir passé en revue mon travail sur LTR et l’adopter sur Datagit
- Crowdin pour leur soutien et leur volonté d'améliorer leur outil
- La communauté Docusaurus pour leur patience, et et les nombreux commentaires utiles sur GitHub
Merci d'avoir pris le temps de lire !
🙏 Et s'il vous plaît, ajoutez vos nouveaux sites i18n à notre galerie. Nous acceptons tous les sites Docusaurus, et nous travaillons sur un redesign vous permettant de filtrer les sites par fonctionnalités.