Ir para o conteúdo principal
Version: 2.0.0-beta.10 🚧

i18n - Introdução

É fácil traduzir um site do Docusaurus com seu suporte à internacionalização (i18n).

Objetivos

É importante entender as decisões de design por trás do suporte Docusaurus i18n.

Para mais contexto, você pode ler a inicial RFC e PR.

objetivos i18n

Os objetivos do sistema Docusaurus i18n são:

  • Simples: basta colocar os arquivos traduzidos no local correto do sistema de arquivos
  • Fluxos de trabalho de tradução flexíveis: use Git (monorepo, forks, ou submódulos), software SaaS, FTP
  • Opções de deploy flexíveis: única, vários domínios ou híbridos
  • Modular: permitir que autores do plugin forneçam suporte do i18n
  • Tempo de execução de baixa sobrecarga: a documentação é principalmente estática e não requer uma biblioteca JS pesada ou polyfills
  • Compilações escalonáveis: permite construir e implantar sites localizados de forma independente
  • Localizar recursos: uma imagem do seu site pode conter texto que deve ser traduzido
  • Nenhum acoplamento: não forçado a usar qualquer SaaS, mas as integrações são possíveis
  • Fácil de usar com o Crowdin: vários sites do Docusaurus v1 usam o Crowdin e podem migrar para a v2
  • Bom padrão de SEO: definimos cabeçalhos de SEO úteis como hreflang para você
  • Suporte RTL: localidades lendo de direita para esquerda (árabe, hebraico, etc.) são suportadas e fáceis de implementar
  • Default translations: classic theme labels are translated for you in many languages

não-objetivo do i18n

Não fornecemos suporte para:

  • Detecção automática de localidade: opinativo e melhor feito no servidor
  • Software de tradução SaaS: você é responsável por entender as ferramentas externas de sua escolha
  • Tradução de slugs: tecnicamente complicado, pouco valor de SEO

Fluxo de trabalho de tradução

Visão Geral

Visão geral do fluxo de trabalho para criar um site traduzido do Docusaurus:

  1. Configure: declare as localidades padrão e locais alternativos em docusaurus.config.js
  2. Traduzir: coloque os arquivos de tradução no local correto do sistema de arquivos
  3. Deploy: faça build e deploy do seu site usando uma estratégia única ou multidomínio

Arquivos de tradução

Você terá que trabalhar com 2 tipos de arquivos de tradução.

Arquivos Markdown

Esse é o conteúdo principal do seu site Docusaurus.

Os documentos Markdown e MDX são traduzidos como um todo, para preservar completamente o contexto da tradução, em vez de dividir cada frase como uma string separada.

Arquivos JSON

JSON é usado para traduzir:

  • seu código React: usando o componente <Translate>
  • seu tema: a barra de navegação, rodapé
  • seus plug-ins: os rótulos de categoria da barra lateral de documentos

O formato JSON usado é chamado de Chrome i18n:

{
"myTranslationKey1": {
"message": "Translated message 1",
"description": "myTranslationKey1 is used on the homepage"
},
"myTranslationKey2": {
"message": "Translated message 2",
"description": "myTranslationKey2 is used on the FAQ page"
}
}

A escolha foi feita por 2 razões:

Localização dos arquivos de tradução

Os arquivos de tradução devem ser criados no local correto do sistema de arquivos.

Cada localidade e plug-in tem sua própria subpasta i18n:

website/i18n/<locale>/<pluginName>/...
note

Para plugins de multi-instância, o caminho é website/i18n/<locale>/<pluginName>-<pluginId>/....

Traduzir um site muito simples do Docusaurus em francês levaria à seguinte árvore:

website/i18n
└── fr
├── code.json

├── docusaurus-plugin-content-blog
│   └── 2020-01-01-hello.md

├── docusaurus-plugin-content-docs
│   ├── current #
│   │   ├── doc1.md
│   │   └── doc2.mdx
│   └── current.json

└── docusaurus-theme-classic
├── footer.json
└── navbar.json

Os arquivos JSON são inicializados com o comando CLI docusaurus write-translations.

O arquivo code.json é extraído dos componentes React usando a API <Translate>.

info

Observe que o plug-in docusaurus-plugin-content-docs tem uma subpasta current e um arquivo current.json, útil para o recurso de controle de versão de documentos.

Cada plugin de conteúdo ou tema é diferente e define seu próprio local de arquivos de tradução: