1.14.4

Translate

Translations & Localization

Docusaurus allows for useful translation functionality using 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
  • The pages/en/help-with-translations.js file includes the same starter help page generated by the examples script but now includes translation tags.

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.

  • The crowdin.yaml file is used to configure Crowdin integration and is copied up one level into your Docusaurus project repo. 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

Pages allow you to customize the layout and specific content of pages like a custom index page or help page.

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>This header will be translated</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="flower, not verb">Rose</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

If you want to add additional custom translation strings or override any of the strings that get produced by the script that creates the website/i18n/en.json file, you can add a website/data/custom-translation-strings.json file. The file should have a form of:

{
  "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. However, maintaining a list of strings used throughout a site can be laborious. O Docusaurus simplifica isso centralizando as strings.

The header navigation, for example, can have links to 'Home' or your '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. When your files are translated, say into Spanish, an i18n/es-ES.json file will be downloaded from 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

For other pages, Docusaurus will automatically transform all <translate> tags it finds into function calls that return the translated strings from the corresponding localized file locale.json.

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. We suggest that you deselect and do not include "English" as a translatable language to prevent the creation of en-US localization files as this can lead to confusion.

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:

# If you only want circle to run on direct commits to master, you can uncomment this out
# and uncomment the filters: *filter-only-master down below too
#
# aliases:
#  - &filter-only-master
#    branches:
#      only:
#        - master

version: 2
jobs:
  deploy-website:
    docker:
      # specify the version you desire here
      - image: circleci/node:8.11.1

    steps:
      - checkout
      - run:
          name: Deploying to 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
            # install Docusaurus and generate file of English strings
            - cd website && yarn install && yarn run write-translations && cd ..
            # crowdin install
            - sudo apt-get install default-jre
            - wget https://artifacts.crowdin.com/repo/deb/crowdin.deb -O crowdin.deb
            - sudo dpkg -i crowdin.deb
            # translations upload/download
            - 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 →