Ir para o conteúdo principal
Version: Canary 🚧

i18n - Usando git

A possible translation strategy is to version control the translation files with Git (or any other VCS).

Tradeoffs

Essa estratégia tem vantagens:

  • Easy to get started: just commit the i18n folder to 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)
  • Pouco atrito: 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
  • Hard for professional translators: they are used to SaaS translation software and advanced features
  • 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.

Inicialização

This is a walk-through of using Git to translate a newly initialized English Docusaurus website into French, and assume you already followed the i18n tutorial.

Preparar o site do Docusaurus

Inicializar um novo site do Docusaurus:

npx create-docusaurus@latest website classic

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

docusaurus.config.js
export default {
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 the write-translations CLI command to initialize the JSON translation files for the French locale:

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/current
cp -r docs/** i18n/fr/docusaurus-plugin-content-docs/current

mkdir -p i18n/fr/docusaurus-plugin-content-blog
cp -r blog/** i18n/fr/docusaurus-plugin-content-blog

mkdir -p i18n/fr/docusaurus-plugin-content-pages
cp -r src/pages/**.md i18n/fr/docusaurus-plugin-content-pages
cp -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
# ou
npm run build -- --locale fr

Repetir

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

Maintenance

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

To help you maintain the JSON translation files, it is possible to run again the write-translations CLI command:

npm run write-translations -- --locale fr

Novas traduções serão anexadas, e as existentes não serão substituídas.

tip

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

Localize edit URLs

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.