1.9.x

Translate

Translations & Localization

O Docusaurus permite que seu site possa ser facilmente traduzido usando o Crowdin. Os arquivos de documentação escritos em inglês são enviados ao Crowdin para serem traduzidos por usuários dentro de uma comunidade. Páginas de nível superior escritas em inglês podem ser traduzidas apenas colocando as strings que você quer traduzidas dentro de tags <translate>. Outros títulos e rótulos também serão encontrados e traduzidos adequadamente.

Configurações de tradução do Docusaurus

Para gerar arquivos de exemplo de traduções do Docusaurus, execute o script examples na linha de comando, juntamente com o argumento translations:

npm run examples translations

ou

yarn examples translations

Isso criará os seguintes arquivos:

pages/en/help-with-translations.js
languages.js
../crowdin.yaml
  • O arquivo pages/en/help-with-translations.js inclui a mesma página de ajuda a iniciantes gerada pelo script examples, mas agora inclui tags de tradução.

No mais, você vai usar mesmo o help-with-translations.js como um guia para ativar traduções em suas outras páginas. Por isso, é melhor não enviar esse arquivo para o seu repositório (ou seja, você pode excluí-lo). No entanto, se você quiser uma página de ajuda e não tiver uma no momento, você pode renomear esse arquivo para help.js e usá-lo como um ponto de partida.

  • O arquivo languages.js diz ao Docusaurus quais idiomas você deseja ativar no seu site. Por padrão, esperamos que o inglês esteja ativado.

  • O arquivo crowdin.yaml é usado para configurar a integração do Crowdin, e é copiado para um nível acima no repositório do seu projeto Docusaurus. Se o seu projeto Docusaurus reside em /projeto/website, então o crowdin.yaml será copiado para /projeto/crowdin.yaml.

Traduzindo sua documentação existente

Seus arquivos de documentação (ou seja, os arquivos .md que vivem em seu diretório docs) não precisam ser alterados nem movidos para que possam ser traduzidos. Eles serão enviados ao Crowdin para serem diretamente traduzidos.

Ativando traduções em páginas

Páginas permitem que você crie e personalize a aparência e o conteúdo específicos para elas, como em uma página inicial personalizada ou uma página de ajuda.

Páginas que tenham textos que você quer traduzidos devem ser colocadas no diretório website/pages/en.

Ponha as strings que você quer traduzidas dentro de uma tag <translate>, e depois adicione a seguinte declaração require lá no começo do arquivo:

...
const translate = require('../../server/translate.js').translate;
...
<h2>
  <translate>Esse título será traduzido</translate>
</h2>
...

Você também pode adicionar uma descrição opcional que dê mais contexto aos tradutores sobre como traduzir a string:

<p>
  <translate desc="a peça de roupa, não o verbo">Saia</translate>
<p>

A tag <translate> geralmente funciona bem em strings de texto puro. If you have a string like "Docusaurus currently provides support to help your website use translations", wrapping the <translation> tag around that entire string will cause issues because of the markdown linking, etc. Em casos assim, você pode ou deixar essas strings sem tradução ou usar um monte de tags <translate> nas partes de texto puro dessa string.

Juntando tudo o que vai ser traduzido

As strings dentro das páginas que serão traduzidas precisam ser extraídas e entregues ao Crowdin.

Adicione o seguinte script ao seu arquivo website/package.json, se já não existir:

{
  ...
  "scripts": {
    "write-translations": "docusaurus-write-translations"
  },
  ...
}

Rodar esse script vai gerar um arquivo website/i18n/en.json contendo todas as strings que serão traduzidas do inglês para outros idiomas.

O script irá incluir o texto dos seguintes locais:

  • Strings de title (título) e sidebar_label (rótulo na barra lateral) dos cabeçalhos de documentos em Markdown
  • Nomes de categorias no sidebars.json
  • A tagline do site no siteConfig.js
  • Os nomes (label) dos itens do menu de navegação dos headerLinks do siteConfig.js
  • Strings que estiverem dentro de tags <translate> em todos os arquivos .js dentro de pages

Strings personalizadas para traduções

Se você quiser adicionar strings personalizadas adicionais para as traduções, ou mesmo sobrescrever qualquer uma das strings em inglês que são produzidas pelo script que cria o arquivo website/i18n/en.json, você pode adicionar um arquivo website/data/custom-translation-strings.json. O arquivo deve ter a seguinte forma:

{
  "localized-strings": {
    "docs": {
      "id": {
        "title": "string1",
        "sidebar_label": "string2"
      },
      "version-0.0.1-id": {
        "title": "string3",
        "sidebar_label": "string4"
      }
    }
  },
  "pages-strings": {
    "id3": "string3",
    "id4": "string4"
  }
}

onde as localized-strings representam strings presentes no conteúdo da sua documentação, e pages-strings representam metadados na sua documentação (p. ex.: títulos, links, etc).

Aqui está um exemplo:

{
  "_comment": "This file is used to provide custom strings for translations, including overriding defaults",
  "localized-strings": {
    "translation": "Translations and Localization"
  },
  "pages-strings": {
    "Help Translate|recruit community translators for your project": "Help Us Translate"
  }
}

Veja o website/i18n/en.json gerado para ver um exemplo.

Como as strings são traduzidas

O Docusaurus sozinho não faz nenhuma tradução de um idioma para outro. Ao invés disso, ele se integra ao Crowdin, enviando a ele tudo que vai ser traduzido e baixando dele os arquivos traduzidos.

Como o Docusaurus usa as strings traduzidas

Essa seção vai explicar um pouco sobre como funcionam as traduções no Docusaurus.

Strings

Um site Docusaurus tem muitas strings usadas por todo o site que precisam de tradução. Porém, manter uma lista das strings usadas por todo o site pode ser uma tarefa árdua. O Docusaurus simplifica isso centralizando as strings.

O menu de navegação, por exemplo, pode ter links para a 'Home' ou para seu 'Blog'. Essas e outras strings encontradas nos menus de navegação, cabeçalhos e barras laterais das páginas são extraídas e colocadas no arquivo i18n/en.json. Quando seus arquivos são traduzidos, por exemplo, para o espanhol, um arquivo i18n/es-ES.json será baixado do Crowdin. Daí, quando as páginas em espanhol são geradas, o Docusaurus irá substituir a versão em inglês das strings correspondentes com as versões traduzidas delas a partir do arquivo com as traduções (ou seja, em um site com traduções para espanhol ativadas, 'Help' vai virar 'Ayuda').

Arquivos Markdown

No caso dos próprios arquivos da documentação, as versões traduzidas desses arquivos serão baixadas e então renderizadas usando o modelo de layout adequado.

Outras páginas

Para outras páginas, o Docusaurus vai automaticamente transformar todas as tags <translate> que ele encontrar em chamadas de função que vão retornar as strings traduzidas presentes no arquivo traduzido locale.json correspondente.

Crowdin

Crowdin é uma empresa que fornece serviços de tradução. O Crowdin disponibiliza seus serviços gratuitamente para projetos de código aberto.

Crie seu projeto de tradução no Crowdin. Você pode seguir os guias do Crowdin para saber mais sobre como funciona o processo de tradução. Sugerimos que você desmarque e não inclua "English" como um idioma traduzível para evitar a criação de arquivos de tradução en-US, já que isso pode levar a confusão.

Garanta que nas suas configurações do Crowdin, na seção Translations, que a opção "Duplicate Strings" esteja configurada como "Hide - all duplicates will share the same translation". Essa configuração irá garantir que strings idênticas entre versões compartilhem uma única tradução.

Seu projeto vai precisar de um arquivo crowdin.yaml gerado. Se você já tiver executado yarn examples translations ou npm run examples translations, então esse arquivo já foi criado pra você no mesmo nível do seu diretório website.

Você precisará instalar a interface de linha de comando do Crowdin. Para isso, siga as instruções de instalação.

O exemplo abaixo code ser gerado automaticamente pela CLI do Docusaurus através do script examples. Ele deve ser colocado no diretório raiz do seu projeto para configurar como e quais arquivos serão enviados/baixados.

Abaixo está um exemplo de configuração do Crowdin para os respectivos idiomas: alemão, espanhol, francês, japonês, coreano, Bahasa Indonésia, português do Brasil, chinês simplificado e chinês tradicional.

project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
api_key_env: CROWDIN_DOCUSAURUS_API_KEY
base_path: './'
preserve_hierarchy: true

files:

  - source: '/docs/**/*.md'
    translation: '/website/translated_docs/%locale%/**/%original_file_name%'
    languages_mapping: &anchor
      locale:
        'de': 'de'
        'es-ES': 'es-ES'
        'fr': 'fr'
        'ja': 'ja'
        'ko': 'ko'
        'mr': 'mr-IN'
        'pt-BR': 'pt-BR'
        'zh-CN': 'zh-CN'
        'zh-TW': 'zh-TW'

Você pode passar aqui para aprender mais sobre como personalizar seu arquivo crowdin.yaml.

Configurando os scripts do Crowdin

Você provavelmente vai querer sincronizar manualmente seus arquivos de e para o Crowdin. O processo de sincronização fará o upload de todos os arquivos Markdown em /docs, bem como as strings traduzíveis em website/i18n/en.json. (Essas strings podem ser geradas executando o script yarn write-translations.)

Você pode adicionar os seguintes scripts ao seu package.json para acionar manualmente o Crowdin.

"scripts": {
  "crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
  "crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
},

Sincronização manual de arquivos

É melhor que você sempre primeiro envie seus arquivos Markdown e strings traduzíveis e depois baixe o que já foi traduzido. Para isso, execute os comandos nesta ordem:

CROWDIN_DOCUSAURUS_PROJECT_ID=SEU_ID_DE_PROJETO_CROWDIN CROWDIN_DOCUSAURUS_API_KEY=SUA_CHAVE_DE_API_CROWDIN yarn run crowdin-upload
CROWDIN_DOCUSAURUS_PROJECT_ID=SEU_ID_DE_PROJETO_CROWDIN CROWDIN_DOCUSAURUS_API_KEY=SUA_CHAVE_DE_API_CROWDIN yarn run crowdin-download

SEU_ID_DE_PROJETO_CROWDIN é o nome do seu projeto no Crowdin. P. ex., no caso de https://crowdin.com/project/docusaurus/, essa variável teria o valor docusaurus. SUA_CHAVE_DE_API_CROWDIN é uma chave única e exclusiva, semelhante a uma senha. Você pode encontrá-la na aba API da página Settings do seu projeto do Crowdin.

Esses comandos exigem que se definam variáveis de ambiente para seu ID de projeto do Crowdin e sua chave de API (CROWDIN_PROJECT_ID, CROWDIN_API_KEY). Você pode defini-las inline, como feito acima, ou adicionar elas permanentemente ao seu .bashrc ou .bash_profile.

Caso você gerencie mais de um projeto do Docusaurus com traduções no seu computador, recomendamos mudar o nome das variáveis de ambiente para algo mais único (ID_CROWDIN_NOMEPROJETO, CHAVE_API_CROWDIN_NOMEPROJETO).

Já que os arquivos são gerados, não é necessário manter nenhum dos arquivos nos seus diretórios website/i18n ou website/translated_docs como parte do seu repositório. Logo, você pode adicionar website/i18n/* e website/translated_docs ao seu arquivo .gitignore.

Sincronização automatizada usando o CircleCI

Você pode automatizar o download e upload de arquivos e traduções usando o serviço de integração contínua CircleCI.

Primeiro de tudo, atualize o arquivo .circleci/config.yml no diretório do seu projeto para incluir as etapas de upload dos arquivos no idioma original a serem traduzidos e de download dos arquivos traduzidos usando a CLI do Crowdin. Aqui está um arquivo .circleci/config.yml de exemplo:

# Se você quiser que o Circle entre em ação apenas em commits diretos à master,
# você pode descomentar as linhas seguintes e também o filtro `*filter-only-master`
# lá embaixo
#
# aliases:
#  - &filter-only-master
#    branches:
#      only:
#        - master

version: 2
jobs:
  deploy-website:
    docker:
      # Especifique aqui a versão desejada

      - image: circleci/node:8.11.1

    steps:

      - checkout
      - run:
          name: Fazendo deploy no GitHub Pages
          command: |
            git config --global user.email 
"<GITHUB_USERNAME>@users.noreply.github.com"
            git config --global user.name "<YOUR_NAME>"
            echo "machine github.com login <GITHUB_USERNAME> password $GITHUB_TOKEN" > ~/.netrc
            # Instala o Docusaurus e gera o arquivo das strings em inglês
            - cd website && yarn install && yarn run write-translations && cd ..
            # Instala o Crowdin
            - sudo apt-get install default-jre
            - wget https://artifacts.crowdin.com/repo/deb/crowdin.deb -O crowdin.deb
            - sudo dpkg -i crowdin.deb
            # Faz o upload/download das traduções
            - crowdin --config crowdin.yaml upload sources --auto-update -b master
            - crowdin --config crowdin.yaml download -b master
            # build and publish website
            cd website && GIT_USER=<GIT_USER> yarn run publish-gh-pages

workflows:
  version: 2
  build_and_deploy:
    jobs:

      - deploy-website:
#         filters: *filter-only-master

O comando crowdin usa o arquivo crowdin.yaml gerado pelo script examples. Ele deve ser colocado no diretório raiz do seu projeto para configurar como e quais arquivos serão enviados/baixados.

Observe que, no arquivo crowdin.yaml, CROWDIN_PROJECT_ID e CROWDIN_API_KEY são variáveis de ambiente relacionadas ao seu projeto do Crowdin e configuradas no Circle. Elas podem ser encontradas nas configurações do seu projeto no Crowdin.

Agora, o Circle vai automatizar para você a sincronização das traduções antes de fazer o processo de build do seu site. O arquivo crowdin.yaml fornecido copiará os documentos traduzidos para website/translated_docs/, e as versões traduzidas do arquivo i18n/en.json serão copiadas para i18n/${idioma}.json.

Caso você deseje usar o Crowdin localmente na sua máquina, você pode instalar a ferramenta de linha de comando do Crowdin e executar os mesmos comandos encontrados no arquivo circle.yaml. A única diferença é que você precisa definir os valores de project_identifier e api_key no arquivo crowdin.yaml, já que você não vai ter as variáveis de ambiente do Circle configuradas.

Traduções versionadas

Caso você deseje manter versões traduzidas para cada versão da sua documentação, adicione a seguinte seção ao fim do seu arquivo crowdin.yaml:

  -
    source: '/website/versioned_docs/**/*.md'
    translation: '/website/translated_docs/%locale%/**/%original_file_name%'
    languages_mapping: *anchor

Documentos traduzidos e versionados serão copiados para website/translated_docs/${idioma}/${versão}/.

← Navigation and SidebarsVersioning →