1.0.13

Translate

Translations & Localization

Docusaurus allows for easy translation functionality using Crowdin. İngilizce olarak yazılmış dokümantasyon dosyaları topluluk tarafından çevrilmesi için Crownd'ine yüklenir. İngilizce yazılmış üst seviye sayfalardaki istenilen dizeler <translate> etiketi ile sarılarak çevrilebilir. Diğer başlık ve etiketlerde bulunup uygunca çevrileceklerdir.

Docusaurus Tercüme Yapılandırmaları

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

npm run examples translations

yada

yarn examples translations

Bu aşağıdaki dosyaları oluşturacaktır:

pages/en/help-with-translations.js
languages.js
../crowdin.yaml
  • pages/en/help-with-translations.js dosyası examples komutunun ürettiği aynı başlangıç yardım sayfasına sahiptir ama bu sefer tercüme etiketleri dahildir.

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.

Mevcut Dosyalarınız Çevirme

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.

Sayfalarda Tercümeyi Etkinleştirme

Sayfalar özelleştirilmiş indeks yada yardım sayfaları gibi belirli içerik sayfalarının yada yerleşim düzeninin özelleştirilmesine izin verir.

Çevirmek istediğiniz metne sahip sayfalar website/pages/en klasörüne yerleştirilmelidir.

Çevirmek istediğiniz dizeleri <translate> etiketi ile sarın ve dosyanın başına gerekli ifadeyi ekleyin:

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

Aynı zamanda çevirmene dizeleri nasıl çevirmesi gerektiğini söyleyebileceğiniz isteğe bağlı açıklama da ekleyebilirsiniz:

<p>
  <translate desc="çiçek, fiil değil">Rose</translate>
<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.

Çevrilecek Dizeleri Toplama

Sayfalar içinde bulunan dizeler ayrılmak ve Crowdin'e sağlanmak zorundadırlar.

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

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

Komutu çalıştırmak İngilizceden diğer dillere çevirilecek her dizeyi barındıran website/i18n/en.json dosyasını oluşturacaktır.

Komut aşağıdaki konumlardan metinler içerecektir:

  • Dokümanın markdown başlıklarında içerisindeki title ve sidebar_label dizeleri
  • sidebars.json içerisindeki kategori isimleri
  • siteConfig.js içerisindeki sloganlar
  • siteConfig.js içerisindeki başlık bağlantı label dizeleri
  • pages içerisindeki herhangi bir .js dosyasındaki <translate> etiketi ile sarılmış dizeler

Dizeler Nasıl Tercüme Edilir

Docusaurus'un kendisi bir dilden başka bir dile çeviri yapmaz. Onun yerine, çevirilecekleri yüklemek ve düzgünce çevirilmişleri indirmek için Crowdin'le etkileşim içindedir.

Docusaurus Dize Tercümelerini Nasıl Kullanır

Bu bölüm Docusaurus'da tercümelerin nasıl çalıştığı hakkında içerik sağlar.

Dizerler

Bir Docusaurus sitesi yerelleştirme gerektiren bir çok dizeye sahiptir. Ancak çevirilecek dizelerin listesini tutmak zahmetli olabilir. Docusaurus simplifies this by centralizing strings.

Başlık gezintisi, örnek olarak 'Ana Sayfa' yada 'Blog' bağlantılarınıza sahip olabilir. Bu ve sayfalarda bulunan diğer başlık ve kenar çubuğu dizeleri, ayrıştırılmışlardır ve i18n/en.json içerisinde yerleştirilmişlerdir. When your files are translated, say into Spanish, a i18n/es-ES.json file will be downloaded from Crowdin. Daha sonra, İspanyolca sayfalar oluşturulur, Docusaurus dizelerin İngilizce sürümü ile karşılık gelen, yerelleştirilmiş dizelerin yerini değiştirir. (örn. İspanyolca etkinleştirilmiş sayfalarda 'Yardım' 'Ayuda' olacaktır).

Markdown Dosyaları

Dokümantasyon sayfalarının kendileri için, tercüme edilmiş dosyalar indirilecek ve daha sonra uygun yerleşim şablonuna göre işlenecekler.

Diğer Sayfalar

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. Daha sorunsuz bir tercüme için Crowdin'in rehberleri kullanabilirsiniz. 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"
},

Manüel Olarak Dosya Eşleştirme

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 circle.yml file in your project directory to include steps to upload English files to be translated and download translated files using the Crowdin CLI. Örnek bir circle.yml dosyası:

machine:
  node:
    version: 6.10.3
  npm:
    version: 3.10.10

test:
  override:

    - "true"

deployment:
  website:
    branch: master
    commands:
      # configure git user

      - git config --global user.email "test-site-bot@users.noreply.github.com"
      - git config --global user.name "Website Deployment Script"
      - echo "machine github.com login test-site-bot password $GITHUB_TOKEN" > ~/.netrc
      # install Docusaurus and generate file of English strings
      - cd website && npm install && npm run write-translations && cd ..
      # crowdin'i yükleme
      - sudo apt-get install default-jre
      - wget https://artifacts.crowdin.com/repo/deb/crowdin.deb -O crowdin.deb
      - sudo dpkg -i crowdin.deb
      # tercüme upload/download
      - crowdin --config crowdin.yaml upload sources --auto-update -b master
      - crowdin --config crowdin.yaml download -b master
      # web sitesini yap ve yayınla
      - cd website && GIT_USER=test-site-bot npm run publish-gh-pages

crowdin komutu examples komutu ile üretilmiş crowdin.yaml dosyasını kullanır. Dosyaların nasıl yükleneceğini/indirileceğini yapılandırmak için proje dizininizin içerisine yerleştirilmelidir.

crowdin.yaml dosyasındaki CROWDIN_PROJECT_ID ve CROWDIN_API_KEY çevresel değişkenlerinin Crowdin projeniz için Daire içerisinde ayarlandığına dikkat edin. Crowdin proje ayarlarında bulunabilirler.

Şimdi, Daire web sitenizin kurulumu için öncelikli olarak otomatik şekilde çevirileri almanıza yardımcı olacak. Sağlanan crowdin.yaml dosyası dokümanları website/translated_docs/ içerisine kopyalayacak ve i18n/en.json dizelerinin tercüme edilmiş halini de i18n/${language}.json içerisine kopyalayacak.

Eğer sizde Crowdin'i makinenizde yerel olarak kullanmak istiyorsanız Crowdin CLI tool'u yükleyebilir ve circle.yaml dosyasındaki aynı kodu çalıştırabilirsiniz. Tek fark Daire çevresel değişkenlerine sahip olmayacağınız için project_identifier'i ve crowdin.yamldosyası içerisindeki api_key değeri ayarlamak zorundasınız.

Sürümlenmiş Tercümeler

Eğer sizde dokümanlarınız için tercüme ve sürümleme istiyorsanız crowdin.yaml'ın sonuna aşağıdaki bölümü ekleyin:

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

Çevrilmiş, sürümlenmiş dokümanlar website/translated_docs/${language}/${version}/ içerisine kopyalanacaklar.

← Navigation and SidebarsVersioning →