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
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:
export default {
i18n: {
defaultLocale: 'en',
locales: ['en', 'fr'],
},
themeConfig: {
navbar: {
items: [
// ...
{
type: 'localeDropdown',
position: 'left',
},
// ...
],
},
},
// ...
};
Traduzir a página inicial:
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
- Yarn
- pnpm
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
yarn 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
pnpm 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
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
- Yarn
- pnpm
npm run start -- --locale fr
yarn run start --locale fr
pnpm run start --locale fr
Você também pode construir o site localmente ou em seu CI:
- npm
- Yarn
- pnpm
npm run build
# ou
npm run build -- --locale fr
yarn build
# ou
yarn build --locale fr
pnpm run build
# ou
pnpm 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
- Yarn
- pnpm
npm run write-translations -- --locale fr
yarn write-translations --locale fr
pnpm run write-translations --locale fr
Novas traduções serão anexadas, e as existentes não serão substituídas.
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
.