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

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 [email protected] 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/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.

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.