Sites traduzidos

Esta página explica como migrar um site Docusaurus v1 traduzido para o Docusaurus v2.

diferenças i18n

Docusaurus v2 i18n é conceitualmente muito semelhante ao Docusaurus v1 i18n, com algumas diferenças.

Ele não está fortemente acoplado ao Crowdin, e você pode usar o Git ou outro SaaS.

Caminhos de sistema de arquivos diferentes

No Docusaurus v2, o conteúdo localizado geralmente é encontrado em website/i18n/<locale>.

Docusaurus v2 é modular baseado em um sistema de plugins, e cada plugin é responsável por gerenciar suas próprias traduções.

Cada plugin tem sua própria pasta de i18n, como: website/i18n/fr/docusaurus-plugin-content-blog

APIs de tradução atualizadas

Com o Docusaurus v1, você traduz suas páginas com <translate>:

const translate = require('../../server/translate.js').translate;
<h2>  <translate desc="the header description">    This header will be translated  </translate></h2>;

No Docusaurus v2, você traduz suas páginas com <Translate>

import Translate from '@docusaurus/Translate';
<h2>  <Translate id="header.translation.id" description="the header description">    This header will be translated  </Translate></h2>;

note

A CLI write-translations ainda funciona para extrair traduções de seu código.

As traduções do código agora são adicionadas a i18n/<lang>/code.json usando o formato JSON do Chrome i18n.

Stricter Markdown parser

O Docusaurus v2 está usando MDX para analisar arquivos Markdown.

MDX compila arquivos Markdown para componentes React, é mais rigoroso que o stricter Docusaurus v1, e irá fazer sua compilação falhar no erro em vez de renderizar algum conteúdo ruim.

Além disso, os elementos HTML devem ser substituídos por elementos JSX.

Isso é particularmente importante para i18n porque se suas traduções não forem boas no Crowdin e usarem marcação inválida, seu site traduzido v2 pode falhar na construção: você pode precisar fazer alguma limpeza de tradução para corrigir os erros.

Estratégias de migração

Esta seção o ajudará a descobrir como manter suas traduções v1 existentes depois de migrar para a v2.

Existem múltiplas estratégias possíveis para migrar um site Docusaurus v1 usando Crowdin, com diferentes compensações.

caution

Esta documentação é o melhor esforço para ajudá-lo a migrar, ajude-nos a melhorá-la se encontrar uma maneira melhor!

Antes de tudo, recomendamos:

• Migre seu site Docusaurus v1 para v2 sem as traduções
• Familiarize-se com o novo sistema i18n do Docusaurus v2 e
• Fazer Crowdin trabalhar para o seu site da v2, usando um projeto novo e não traduzido do Crowdin e o tutorial do Crowdin

danger

Não tente migrar sem entender o Crowdin e o Docusaurus v2 i18n.

Criar um novo projeto no Crowdin

Para evitar qualquer risco de interromper seu site v1 em produção, uma estratégia possível é duplicar o projeto Crowdin v1 original.

info

Esta estratégia foi usada para atualizar o site Jest.

Infelizmente, o Crowdin não tem qualquer recurso "Duplicar/clonar Projeto", o que torna as coisas complicadas.

• Baixe a memória de tradução de seu projeto original no formato .tmx ( https://crowdin.com/project/<ORIGINAL_PROJECT>/settings#tm>Exibir registros)
• Enviar a memória de tradução para o seu novo projeto (https://crowdin.com/project/<NEW_PROJECT>/settings#tm > Ver Registros
• Reconfigurar crowdin.yml para o Docusaurus v2 de acordo com a documentação de i18n
• Carregar os arquivos fonte do Docusaurus v2 com o CLI do Crowdin para o novo projeto
• Marcar frases sensíveis como id ou slug como "hidden string" no Crowdin
• Na guia "Traduções", clique em "Pré-Tradução > via TM" (https://crowdin.com/project/<NEW_PROJECT>/settings#translations)
• Tente primeiro com "correspondência 100%" (mais conteúdo será traduzido do que "Perfeito") e pré-traduza suas fontes
• Baixar localmente as traduções do Crowdin
• Tente executar/construir seu site e veja se há algum erro

Você provavelmente terá erros na sua primeira tentativa: a pré-tradução pode tentar traduzir coisas que não devem ser traduzidas (frontmatter, admonition, code blocks...), e os arquivos md traduzidos podem ser inválidos para o analisador MDX.

Você terá que corrigir todos os erros até que seu site seja criado. Você pode fazer isso modificando os arquivos md traduzidos localmente e corrigir seu site para um local de cada vez usando docusaurus build --locale fr.

Não existe um guia definitivo que possamos escrever para corrigir esses erros, mas os erros comuns são devidos a:

• Não marcar strings suficientes como "hidden strings" no Crowdin, levando à pré-tradução tentando traduzir essas strings.
• Ter traduções ruins v1, levando a marcação inválida na v2: elementos html inválidos dentro de traduções e tags não fechadas
• Qualquer coisa rejeitada pelo analisador MDX, como usar elementos HTML em vez de elementos JSX (use o playground MDX para depuração)

Você pode querer repetir este processo de pré-tradução, eventualmente tentando a opção "Perfect" e limitando a pré-tradução apenas alguns idiomas/arquivos.

tip

Use mdx-code-block em torno de elementos de marcação problemáticos: Crowdin é menos provável que bagunce as coisas com blocos de código.

note

Você provavelmente notará que algumas coisas foram traduzidas em seu projeto antigo, mas agora não estão traduzidas em seu novo projeto.

O analisador Crowdin Markdown está evoluindo outra vez e cada projeto Crowdin tem uma versão de analisador diferente, o que pode fazer com que a pré-tradução não seja capaz de pré-traduzir todas as strings.

Esta versão do analisador não está documentada e você terá que pedir ao suporte Crowdin para saber a versão do analisador do seu projeto e corrigir uma versão específica.

Usar a mesma versão cli e versão do analisador nos 2 projetos Crowdin pode dar melhores resultados.

danger

Crowdin tem um recurso de "upload de traduções", mas em nossa experiência não dá resultados muito bons para Markdown

Use o projeto Crowdin existente

Se você não se importa em modificar seu projeto Crowdin existente e arriscar bagunçar as coisas, pode ser possível usar o sistema de ramificação Crowdin.

caution

Este fluxo de trabalho não foi testado na prática, informe-nos como ele é bom.

Dessa forma, você não precisaria criar um novo projeto Crowdin, transferir a memória de tradução, aplicar pré-traduções e tentar corrigir os erros de pré-traduções.

Você poderia criar um branch Crowdin para Docusaurus v2, onde você carrega as fontes v2, e mescla o branch Crowdin para master quando estiver pronto.

Usar o Git em vez do Crowdin

É possível migrar para fora do Crowdin e adicionar os arquivos de tradução ao Git.

Use a CLI do Crowdin para baixar os arquivos traduzidos da v1 e coloque esses arquivos traduzidos no local correto do sistema de arquivos Docusaurus v2.