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

i18n - Usando git

Uma possível estratégia de tradução é controlar a versão dos arquivos de tradução para o Git (ou qualquer outro VCS ).

Tradeoffs#

Essa estratégia tem vantagens:

  • Fácil de começar: basta adicionar a pasta i18n ao Git
  • Fácil para desenvolvedores: Git, GitHub e pull requests são ferramentas de desenvolvedor
  • Grátis (ou sem qualquer custo adicional, assumindo que você já usou o Git)
  • Baixa fricção: não requer inscrição em uma ferramenta externa
  • Recompensa: Os colaboradores estão felizes em ter um bom histórico de contribuições

O uso do Git também apresenta algumas deficiências:

  • Difícil para não desenvolvedores: eles não dominam Git e solicitações pull
  • Difícil para traduções profissionais: eles são usados para softwares de tradução SaaS e recursos avançados
  • Difícil de manter: você deve manter os arquivos traduzidos sincronizados com os arquivos não traduzidos
note

Alguns projetos técnicos de grande escala (React, Vue.js, MDN, TypeScript, Nuxt.js, etc.) usam Git para traduções.

Consulte a RFC Docusaurus i18n para nossas notas e links que estudam esses sistemas.

Tutorial Git#

Este é um passo a passo sobre o uso do Git para traduzir um site do Docusaurus em inglês recém-inicializado para o francês, e presume que você já seguiu o i18n tutorial.

Preparar o site do Docusaurus#

Inicializar um novo site do Docusaurus:

npx @docusaurus/init@latest init website classic

Adicione a configuração do site para o idioma francês:

docusaurus.config.js
module.exports = {  i18n: {    defaultLocale: 'en',    locales: ['en', 'fr'],  },  themeConfig: {    navbar: {      items: [        // ...        {          type: 'localeDropdown',          position: 'left',        },        // ...      ],    },  },  // ...};

Traduzir a página inicial:

src/pages/index.js
import React from 'react';import Translate from '@docusaurus/Translate';import Layout from '@theme/Layout';
export default function Home() {  return (    <Layout>      <h1 style={{margin: 20}}>        <Translate description="The homepage main heading">          Welcome to my Docusaurus translated site!        </Translate>      </h1>    </Layout>  );}

Inicialize a pasta i18n#

Use o comando CLI write-translations para inicializar os arquivos de tradução JSON para o idioma francês:

npm run write-translations -- --locale fr
  1 translations written at i18n/fr/code.json 11 translations written at i18n/fr/docusaurus-theme-classic/footer.json  4 translations written at i18n/fr/docusaurus-theme-classic/navbar.json  3 translations written at i18n/fr/docusaurus-plugin-content-docs/current.json
tip

Use a opção --messagePrefix '(fr) ' para destacar as strings não traduzidas.

Hello aparecerá como (fr) Hello e deixa claro que falta uma tradução.

Copie seus arquivos Markdown não traduzidos para a pasta francesa:

mkdir -p i18n/fr/docusaurus-plugin-content-docs/currentcp -r docs/** i18n/fr/docusaurus-plugin-content-docs/current
mkdir -p i18n/fr/docusaurus-plugin-content-blogcp -r blog/** i18n/fr/docusaurus-plugin-content-blog
mkdir -p i18n/fr/docusaurus-plugin-content-pagescp -r src/pages/**.md i18n/fr/docusaurus-plugin-content-pagescp -r src/pages/**.mdx i18n/fr/docusaurus-plugin-content-pages

Adicionar todos esses arquivos ao Git.

Traduzir os arquivos#

Traduza os arquivos Markdown e JSON em i18n/fr e faça commit da tradução.

Agora você deve poder iniciar seu site em francês e ver as traduções:

npm run start -- --locale fr

Você também pode construir o site localmente ou em seu CI:

npm run build# ounpm run build -- --locale fr

Repetir#

Siga o mesmo processo para cada localidade que você precisa oferecer suporte.

Manter as traduções#

Manter os arquivos traduzidos consistentes com os originais pode ser um desafio, em particular para documentos Markdown.

Traduções Markdown#

Quando um documento Markdown não traduzido é editado, é sua responsabilidade manter os respectivos arquivos traduzidos e, infelizmente, não temos uma boa maneira de ajudá-lo a fazer isso.

Para manter seus sites traduzidos consistentes, quando o documento website/docs/doc1.md for editado, você precisará fazer backport dessas edições para i18n/fr/docusaurus-plugin-content-docs/current/doc1.md.

Traduções JSON#

Para ajudá-lo a manter os arquivos de tradução JSON, é possível executar novamente o comando CLI write-translations:

npm run write-translations -- --locale fr

Nova tradução será anexada e as já existentes não serão substituídas.

tip

Redefina suas traduções com a opção --override.

Localizar Urls de edição#

Quando o usuário está navegando em uma página em /fr/doc1, o botão de edição será vinculado por padrão ao documento não localizado em website/docs/doc1.md.

Suas traduções estão no Git e você pode usar a opção editLocalizedFiles: true dos documentos e plug-ins de blog.

O botão de edição irá vincular para o documento localizado em i18n/fr/docusaurus-plugin-content-docs/current/doc1.md.