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

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
  • Traduções padrão: rótulos do tema clássico são traduzidos para você em vários idiomas

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: