1.10.x

Translate

Translations & Localization

Docusaurus allows for easy translation functionality using Crowdin. Fișierele de documentație scrise în engleză sunt încărcate pe Crowdin pentru o traducere a utilizatorilor din comunitate. Paginile de nivel înalt scrise cu șiruri în limba engleză pot fi traduse prin încercuirea tuturor șirurilor pe care vrei să le traduci într-un tag <traduce>. Alte titluri și etichete pot fi deasemenea găsite și traduse corespunzător.

Configurații traduceri Docusaurus

To generate example files for translations with Docusaurus, run the examples script with the command line argument translations:

npm run exemple traduceri

sau

yarn exemple traduceri

Aceasta va crea următoarele fișiere:

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.

Generally, you will use help-with-translations.js as a guide to enable translations in your other pages, but not actually commit the file to your repo (i.e., you can delete it). However, if you want a Help page, and you currently do not have one, you can rename this file to help.js and use it as a starting point.

  • The languages.js file tells Docusaurus what languages you want to enable for your site. By default, we expect English to be enabled.

  • The crowdin.yaml file is used to configure Crowdin integration and is copied up one level into your Docusaurus project repo. If your Docusaurus project resides in /project/website, then crowdin.yaml will be copied to /project/crowdin.yaml.

Traducând documentele tale existente

Your documentation files (e.g., the .md files that live in your docs directory) do not need to be changed or moved to support translations. They will be uploaded to Crowdin to be translated directly.

Activând traducerile pe Pagini

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

Pages with text that you want translated should be placed in website/pages/en directory.

Încercuiește șirurile pe care vrei să le traduci într-un tag <traduce>, apoi adaugă următoarele declarații de tip require în capul fișierului:

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

Poţi deasemenea să incluzi un atribut de descriere opțională pentru a da mai mult context pentru un traducător despre cum să traducă acel șir:

<p>
  <traduce desc="floare, nu verb">Rose</traduce>
<p>

The <translate> tag generally works well on pure strings. 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. Your options are to not translate those strings, or spread a bunch of <translate> tags amongst the pure substrings of that string.

Adunând șirurile pentru a Traduce

Șirurile din paginile de localizare trebuiesc extrase și furnizate lui Crowdin.

Add the following script to your website/package.json file, if it does not exist already:

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

Rulând acest script va genera un fișier siteweb/i18n/en.json conținând toate șirurile ce vor fi traduse din engleză în alte limbi.

Acest script include text din următoarele locuri:

  • Șirurile titlu și etichetă_sidebar din header-ele de markdown ale documentului
  • nume categorii în sidebars.json
  • tagline în siteConfig.js
  • șirurile link header etichetă în siteConfig.js
  • șirurile încercuite în tag-ul <traduce> în orice fișier .js în interiorul pagini

Custom Translation Strings

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"
  }
}

where localized-strings represent strings in your documentation content and pages-strings represents metadata in your documentation (e.g., title, links, etc).

Here is an example:

{
  "_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"
  }
}

See the generated website/i18n/en.json for an example.

Cum se traduc șirurile

Docusaurus însăși nu face nici o traducere dintr-o limbă în alta. În locul acesteia, el integrează Crowdin pentru a încărca traduceri și apoi descarcă fișierele respective traduse din Crowdin.

Cum folosește Docusaurus traducerile de șiruri

Această secțiune furnizează context despre cum funcționează traducerile în Docusaurus.

Șiruri

Un site Docusaurus are multe șiruri utilizate prin el care au nevoie de localizare. However, maintaining a list of strings used throughout a site can be laborious. Docusaurus simplifies this by centralizing strings.

The header navigation, for example, can have links to 'Home' or your 'Blog'. Aceasta sau alte șiruri găsite în header-ele și sidebar-urile paginilor sunt extrase și plasate în i18n/en.json. When your files are translated, say into Spanish, an i18n/es-ES.json file will be downloaded from Crowdin. Apoi, când paginile în spaniolă sunt generate, Docusaurus va înlocui versiunea în engleză a șirurilor corespunzătoare cu șirurile traduse din fișierul de localizare cu șiruri corespunzător (ex. Într-un site cu spaniola activată 'Help' va deveni 'Ayuda').

Fișiere Markdown

Pentru fișierele de documentație însăși, versiunile traduse așe acestor fișiere sunt descărcate și apoi redate prin template-ul de layout corespunzător.

Alte pagini

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 is a company that provides translation services. For Open Source projects, Crowdin provides free string translations.

Create your translation project on Crowdin. Poți să folosești Ghiduri-le Crowdin pentru a afla mai multe despre work flow-ul traducerilor. 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.

Ensure in your Crowdin settings, in the Translations section, that "Duplicate Strings" are set to "Hide - all duplicates will share the same translation". This setting will ensure that identical strings between versions share a single translation.

Your project will need a crowdin.yaml file generated. If you ran yarn examples translations or npm run examples translations, this file was created for you on the same level as your website directory.

You will need to install the crowdin command line interface. Please follow the installation directions.

The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

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'

You can go here to learn more about customizing your crowdin.yaml file.

Setup the Crowdin Scripts

You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

You can add the following to your package.json to manually trigger Crowdin.

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

Sincronizare fișier manuală

You will always want to upload your markdown files and translatable strings first and the download the translations section. So run the commands in this order:

CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-download

YOUR_CROWDIN_PROJECT_ID is the name of your Crowdin project. e.g., for https://crowdin.com/project/docusaurus/, that variable would be set to docusaurus. YOUR_CROWDIN_API_KEY is a unique key that is like a password. You can find it in the API tab of your Crowdin project's Settings.

These commands require having an environment variable set with your Crowdin project id and api key (CROWDIN_PROJECT_ID, CROWDIN_API_KEY). You can preface them inline as done above or add them permanently to your .bashrc or .bash_profile.

If you run more than one localized Docusaurus project on your computer, you should change the name of the environment variables to something unique (CROWDIN_PROJECTNAME_PROJECT_ID, CROWDIN_PROJECTNAME_API_KEY).

Since the files are generated, you do not need to have any files in your website/i18n or website/translated_docs directory as part of your repo. So you can can add website/i18n/* and website/translated_docs to your .gitignore file.

Automated File Sync Using CircleCI

You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

First, update the .circleci/config.yml file in your project directory to include steps to upload English files to be translated and download translated files using the Crowdin CLI. Here is an example .circleci/config.yml file:

# 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

Comanda crowdin utilizează fișierul crowdin.yaml generat cu script-ul exemple. Ar trebuii plasat în directorul proiectului tău pentru a configura cum și ce fișiere sunt încărcate/descărcate.

Ia aminte că în fișierul crowdin.yaml, CROWDIN_PROJECT_ID și CROWDIN_API_KEY sunt variabile de environment setate în Circle pentru proiectul tău Crowdin. Pot fi găsite în setările proiectului tău Crowdin.

Acum, Circle te va ajuta să iei traducerile automat înainte să îți construiești site-ul web. Fișierul crowdin.yaml furnizat va copia documentele traduse în siteweb/documente_traduse/, și versiunile traduse a fișierului de șiruri i18n/en.json în i18n/${language}.json.

Dacă dorești să utilizezi Crowdin pe server-ul tău local, poți să instalezi unealta Crodin CLI și să rulezi aceleași comenzi găsite în fișierul circle.yaml. Singura diferență este ca trebuie să setezi valorile project_identifier și api_key în fișierul crowdin.yaml, din moment ce nu vei avea variabilele de environment Circle de setat.

Traduceri versionate

Dacă dorești să ai traducere și versionare pentru documentația ta, adaugă următoarea secțiune la finalul fișierului tău crowdin.yaml:

  -
    sursă: '/siteweb/documente_versionate/**/*.md'
    traducere: '/siteweb/documente_traduses/%locale%/**/%original_file_name%'
    mapping_limbi: *anchor

Documentele traduse, versionate vor fi copiate în siteweb/documente_traduse/${language}/${version}/.

← Navigation and SidebarsVersioning →