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
On Docusaurus v2, localized content is generally found at 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>;
A CLI write-translations ainda funciona para extrair traduções de seu código.
The code translations are now added to i18n/[locale]/code.json using Chrome i18n JSON format.
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.
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
- Get familiar with the new i18n system of Docusaurus v2 an
- Fazer Crowdin trabalhar para o seu site da v2, usando um projeto novo e não traduzido do Crowdin e o tutorial do Crowdin
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.
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.ymlpara 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
idouslugcomo "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
You will likely have errors on your first-try: the pre-translation might try to translate things that it should not be translated (front matter, admonition, code blocks...), and the translated MD files might be invalid for the MDX parser.
Você terá que corrigir todos os erros até que seu site seja criado. You can do that by modifying the translated MD files locally, and fix your site for one locale at a time using 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.
- Having bad v1 translations, leading to invalid markup in v2: bad HTML elements inside translations and unclosed tags
- 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.
Use mdx-code-block around problematic Markdown elements: Crowdin is less likely mess things up with code blocks.
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.
Using the same CLI version and parser version across the 2 Crowdin projects might give better results.
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.
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.
You could create a Crowdin branch for Docusaurus v2, where you upload the v2 sources, and merge the Crowdin branch to main once ready.
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.