mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-12 00:27:21 +02:00
181 lines
No EOL
30 KiB
HTML
181 lines
No EOL
30 KiB
HTML
<html lang="en"><head><meta charset="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge, chrome=1"/><title>Translations & Localization · Docusaurus</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta property="og:title" content="Translations & Localization · Docusaurus"/><meta property="og:type" content="website"/><meta property="og:url" content="https://docusaurus.io/index.html"/><meta property="og:description" content="Docusaurus allows for easy translation functionality using [Crowdin](https://crowdin.com/). Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a `<translate>` tag. Other titles and labels will also be found and properly translated."/><meta property="og:image" content="https://docusaurus.io/img/docusaurus.png"/><link rel="shortcut icon" href="/img/docusaurus.ico"/><link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css"/><link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/solarized-dark.min.css"/><link rel="alternate" type="application/atom+xml" href="https://docusaurus.io/blog/atom.xml" title="Docusaurus Blog ATOM Feed"/><link rel="alternate" type="application/rss+xml" href="https://docusaurus.io/blog/feed.xml" title="Docusaurus Blog RSS Feed"/><script type="text/javascript" src="https://buttons.github.io/buttons.js"></script><link rel="stylesheet" href="/css/main.css"/></head><body class="sideNavVisible"><div class="fixedHeaderContainer"><div class="headerWrapper wrapper"><header><a href="/"><img class="logo" src="/img/docusaurus.svg"/><h2 class="headerTitle">Docusaurus</h2></a><div class="navigationWrapper navigationSlider"><nav class="slidingNav"><ul class="nav-site nav-site-internal"><li><a href="/docs/installation.html" target="_self">Docs</a></li><li><a href="/en/help.html" target="_self">Help</a></li><li><a href="/en/about-slash.html" target="_self">About /</a></li><li><a href="/blog" target="_self">Blog</a></li><li><a href="https://github.com/facebook/docusaurus" target="_self">GitHub</a></li><li class="navSearchWrapper reactNavSearchWrapper"><input type="text" id="search_input_react" placeholder="Search"/></li></ul></nav></div></header></div></div><div class="navPusher"><div class="docMainWrapper wrapper"><div class="container docsNavContainer" id="docsNav"><nav class="toc"><div class="toggleNav"><section class="navWrapper wrapper"><div class="navBreadcrumb wrapper"><div class="navToggle" id="navToggler"><i></i></div><h2><i>›</i><span>Guides</span></h2></div><div class="navGroups"><div class="navGroup navGroupActive"><h3>Getting Started</h3><ul><li class="navListItem"><a class="navItem" href="/docs/installation.html">Installation</a></li><li class="navListItem"><a class="navItem" href="/docs/site-preparation.html">Site Preparation</a></li><li class="navListItem"><a class="navItem" href="/docs/site-creation.html">Creating your site</a></li><li class="navListItem"><a class="navItem" href="/docs/publishing.html">Publishing your site</a></li></ul></div><div class="navGroup navGroupActive"><h3>Guides</h3><ul><li class="navListItem"><a class="navItem" href="/docs/blog.html">Adding a Blog</a></li><li class="navListItem"><a class="navItem" href="/docs/custom-pages.html">Custom Pages</a></li><li class="navListItem"><a class="navItem" href="/docs/search.html">Enabling Search</a></li><li class="navListItem"><a class="navItem" href="/docs/navigation.html">Navigation and Sidebars</a></li><li class="navListItem navListItemActive"><a class="navItem navItemActive" href="/docs/translation.html">Translations & Localization</a></li><li class="navListItem"><a class="navItem" href="/docs/versioning.html">Versioning</a></li></ul></div><div class="navGroup navGroupActive"><h3>API</h3><ul><li class="navListItem"><a class="navItem" href="/docs/commands.html">CLI Commands</a></li><li class="navListItem"><a class="navItem" href="/docs/doc-markdown.html">Markdown Features</a></li><li class="navListItem"><a class="navItem" href="/docs/api-pages.html">Pages and Styles</a></li><li class="navListItem"><a class="navItem" href="/docs/site-config.html">siteConfig.js</a></li></ul></div></div></section></div><script>
|
||
var toggler = document.getElementById('navToggler');
|
||
var nav = document.getElementById('docsNav');
|
||
toggler.onclick = function() {
|
||
nav.classList.toggle('docsSliderActive');
|
||
};
|
||
</script></nav></div><div class="container mainContainer"><div class="wrapper"><div class="post"><header class="postHeader"><a class="edit-page-link button" href="https://github.com/facebook/docusaurus/edit/master/docs/guides-translation.md" target="_blank">Edit</a><h1>Translations & Localization</h1></header><article><div><span><p>Docusaurus allows for easy translation functionality using <a href="https://crowdin.com/">Crowdin</a>. Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a <code><translate></code> tag. Other titles and labels will also be found and properly translated.</p>
|
||
<h2><a class="anchor" aria-hidden="true" name="docusaurus-translation-configurations"></a><a href="#docusaurus-translation-configurations" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Docusaurus Translation Configurations</h2>
|
||
<p>To generate example files for translations with Docusuaurus, run the <code>examples</code> script with the command line argument <code>translations</code>:</p>
|
||
<pre><code class="hljs">npm <span class="hljs-keyword">run</span><span class="bash"> examples translations
|
||
</span></code></pre>
|
||
<p>or</p>
|
||
<pre><code class="hljs"><span class="hljs-attribute">yarn examples translations</span>
|
||
</code></pre>
|
||
<p>This will create the following files:</p>
|
||
<pre><code class="hljs">pages/en/help-with-translations<span class="hljs-selector-class">.js</span>
|
||
languages<span class="hljs-selector-class">.js</span>
|
||
../crowdin<span class="hljs-selector-class">.yaml</span>
|
||
</code></pre>
|
||
<p>The <code>pages/en/help-with-translations.js</code> file includes the same starter help page generated by the <code>examples</code> script, but now includes translation tags.</p>
|
||
<p>The <code>languages.js</code> file tells Docusaurus what languages you want to enable for your site. By default, we expect English to be enabled.</p>
|
||
<p>The <code>crowdin.yaml</code> file is used to configure crowdin integration, and is copied up one level into your docusaurus project repo. If your docusaurus project resides in <code>/project/website</code>, then <code>crowdin.yaml</code> will be copied to <code>/project/crowdin.yaml</code>.</p>
|
||
<h2><a class="anchor" aria-hidden="true" name="translating-your-existing-docs"></a><a href="#translating-your-existing-docs" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Translating Your Existing Docs</h2>
|
||
<p>Your documentation files do not need to be changed or moved to support translations. They will be uploaded to Crowdin to be translated directly.</p>
|
||
<h2><a class="anchor" aria-hidden="true" name="enabling-translations-on-pages"></a><a href="#enabling-translations-on-pages" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Enabling Translations on Pages</h2>
|
||
<p>Pages allow you to customize layout and specific content of pages like a custom index page or help page.</p>
|
||
<p>Pages with text that you want translated should be placed in <code>website/pages/en</code> folder.</p>
|
||
<p>Wrap strings you want translated in a <code><translate></code> tag, and add the following <code>require</code> statement to the top of the file:</p>
|
||
<pre><code class="hljs css jsx">...
|
||
const translate = require("../../server/translate.js").translate;
|
||
...
|
||
<h2>
|
||
<translate>This header will be translated</translate>
|
||
</h2>
|
||
...
|
||
</code></pre>
|
||
<p>You can also include an optional description attribute to give more context to a translator about how to translate the string:</p>
|
||
<pre><code class="hljs css jsx"><p>
|
||
<span class="xml"><span class="hljs-tag"><<span class="hljs-name">translate</span> <span class="hljs-attr">desc</span>=<span class="hljs-string">"flower, not verb"</span>></span>Rose<span class="hljs-tag"></<span class="hljs-name">translate</span>></span></span>
|
||
<p>
|
||
</code></pre>
|
||
<h2><a class="anchor" aria-hidden="true" name="gathering-strings-to-translate"></a><a href="#gathering-strings-to-translate" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Gathering Strings to Translate</h2>
|
||
<p>The strings within localized Pages must be extracted and provided to Crowdin.</p>
|
||
<p>Add the following script to your package.json file:</p>
|
||
<pre><code class="hljs css json">...
|
||
"scripts": {
|
||
"write-translations": "docusaurus-write-translations"
|
||
},
|
||
...
|
||
</code></pre>
|
||
<p>Running the script will generate a <code>website/i18n/en.json</code> file containing all the strings that will be translated from English into other languages.</p>
|
||
<p>The script will include text from the following places:</p>
|
||
<ul>
|
||
<li><code>title</code> and <code>sidebar_label</code> strings in document markdown headers</li>
|
||
<li>category names in <code>sidebars.json</code></li>
|
||
<li>tagline in <code>siteConfig.js</code></li>
|
||
<li>header link <code>label</code> strings in <code>siteConfig.js</code></li>
|
||
<li>strings wrapped in the <code><translate></code> tag in any <code>.js</code> files inside <code>pages</code></li>
|
||
</ul>
|
||
<h2><a class="anchor" aria-hidden="true" name="how-strings-get-translated"></a><a href="#how-strings-get-translated" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>How Strings Get Translated</h2>
|
||
<p>Docusaurus itself does not do any translation from one language to another. Instead, it integrates <a href="https://crowdin.com/">Crowdin</a> to upload translations and then downloads the appropriately translated files from Crowdin.</p>
|
||
<h2><a class="anchor" aria-hidden="true" name="how-docusaurus-uses-string-translations"></a><a href="#how-docusaurus-uses-string-translations" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>How Docusaurus Uses String Translations</h2>
|
||
<p>This section provides context about how translations in Docusaurus works.</p>
|
||
<h3><a class="anchor" aria-hidden="true" name="strings"></a><a href="#strings" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Strings</h3>
|
||
<p>A Docusaurus site has many strings used throughout it that require localization. However, maintaining a list of strings used through out a site can be laborious. Docusaurus simplifies this by centralizing strings.</p>
|
||
<p>The header navigation, for example can have links to 'Home' or your 'Blog'. This and other strings found in the headers and sidebars of pages are extracted and placed into <code>i18n/en.json</code>. When your files are translated, say into Spanish, a <code>i18n/es-ES.json</code> file will be downloaded from Crowdin. Then, when the Spanish pages are generated, Docusaurus will replace the English version of corresponding strings with translated strings from the corresponding localized strings file (e.g. In a Spanish enabled site 'Help' will become 'Ayuda').</p>
|
||
<h3><a class="anchor" aria-hidden="true" name="markdown-files"></a><a href="#markdown-files" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Markdown Files</h3>
|
||
<p>For documentation files themselves, translated versions of these files are downloaded and then rendered through the proper layout template.</p>
|
||
<h3><a class="anchor" aria-hidden="true" name="other-pages"></a><a href="#other-pages" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Other Pages</h3>
|
||
<p>For other pages, Docusaurus will automatically transform all <code><translate></code> tags it finds into function calls that return the translated strings from the corresponding localized file <em><code>locale.json</code></em>.</p>
|
||
<h2><a class="anchor" aria-hidden="true" name="crowdin"></a><a href="#crowdin" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Crowdin</h2>
|
||
<p>Crowdin is a company that provides translation services. For Open Source projects, Crowdin provides free string translations</p>
|
||
<p>Create your translation project on <a href="https://crowdin.com/">Crowdin</a>. You can use <a href="https://support.crowdin.com/translation-process-overview/">Crowdin's guides</a> to learn more about the translations work flow. <em>We suggest that you deselect and do not include "English" as a translateable language to prevent the creation of <code>en-US</code> localization files as this can lead to confusion.</em></p>
|
||
<p>Your project will need a <code>crowdin.yaml</code> file generated.</p>
|
||
<blockquote>
|
||
<p>You will need to install <code>crowdin-cli</code>. Please follow the <a href="https://support.crowdin.com/cli-tool/">installation directions</a>.</p>
|
||
</blockquote>
|
||
<p>The example below can be automatically generated by the docusaurus cli with the <code>examples</code> script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.</p>
|
||
<p>Below is an example crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Behasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.</p>
|
||
<pre><code class="hljs css yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||
<span class="hljs-attr">api_key_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_API_KEY</span>
|
||
<span class="hljs-attr">base_path:</span> <span class="hljs-string">"./"</span>
|
||
<span class="hljs-attr">preserve_hierarchy:</span> <span class="hljs-literal">true</span>
|
||
|
||
<span class="hljs-attr">files:</span>
|
||
<span class="hljs-bullet"> -</span>
|
||
<span class="hljs-attr"> source:</span> <span class="hljs-string">'/docs/*.md'</span>
|
||
<span class="hljs-attr"> translation:</span> <span class="hljs-string">'/website/translated_docs/%locale%/%original_file_name%'</span>
|
||
<span class="hljs-attr"> languages_mapping:</span> <span class="hljs-meta">&anchor</span>
|
||
<span class="hljs-attr"> locale:</span>
|
||
<span class="hljs-attr"> 'de':</span> <span class="hljs-string">'de'</span>
|
||
<span class="hljs-attr"> 'es-ES':</span> <span class="hljs-string">'es-ES'</span>
|
||
<span class="hljs-attr"> 'fr':</span> <span class="hljs-string">'fr'</span>
|
||
<span class="hljs-attr"> 'ja':</span> <span class="hljs-string">'ja'</span>
|
||
<span class="hljs-attr"> 'ko':</span> <span class="hljs-string">'ko'</span>
|
||
<span class="hljs-attr"> 'mr':</span> <span class="hljs-string">'mr-IN'</span>
|
||
<span class="hljs-attr"> 'pt-BR':</span> <span class="hljs-string">'pt-BR'</span>
|
||
<span class="hljs-attr"> 'zh-CN':</span> <span class="hljs-string">'zh-Hans'</span>
|
||
<span class="hljs-attr"> 'zh-TW':</span> <span class="hljs-string">'zh-Hant'</span>
|
||
</code></pre>
|
||
<p>You can go <a href="https://support.crowdin.com/configuration-file/">here</a> to learn more about customizing your <code>crowdin.yaml</code> file.</p>
|
||
<h3><a class="anchor" aria-hidden="true" name="manual-file-sync"></a><a href="#manual-file-sync" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Manual File Sync</h3>
|
||
<p>You will want to manually sync your files to and from crowdin. The sync process will upload any markdown files in <code>/docs</code> as well as translatable strings in <code>website/i18n/en.json</code>. (These strings can be generated by running <code>yarn write-translations</code>.)</p>
|
||
<p>You can add the following to your <code>package.json</code> to manually trigger crowdin.</p>
|
||
<pre><code class="hljs css json">"scripts": {
|
||
"crowdin-upload": "export CROWDIN_DOCUSAURUS_PROJECT_ID=$YOUR_CROWDIN_ID;
|
||
export CROWDIN_DOCUSAURUS_API_KEY=$YOUR_CROWDIN_API_KEY; crowdin-cli --config ../crowdin.yaml upload sources --auto-update -b master",
|
||
"crowdin-download": "export CROWDIN_DOCUSAURUS_PROJECT_ID=$YOUR_CROWDIN_ID;
|
||
export CROWDIN_DOCUSAURUS_API_KEY=$YOUR_CROWDIN_API_KEY; crowdin-cli --config ../crowdin.yaml download -b master"
|
||
},
|
||
</code></pre>
|
||
<p>These commands require having an environment variable set with your crowdin project id and api key (<code>CROWDIN_PROJECT_ID</code>, <code>CROWDIN_API_KEY</code>). You can add them inline like above or add them permanently to your <code>.bashrc</code> or <code>.bash_profile</code>.</p>
|
||
<p>If you run more than one localized Docusaurus project on your computer, you should change the name of the enviroment variables to something unique (<code>CROWDIN_PROJECTNAME_PROJECT_ID</code>, <code>CROWDIN_PROJECTNAME_API_KEY</code>).</p>
|
||
<h3><a class="anchor" aria-hidden="true" name="automated-file-sync-using-circleci"></a><a href="#automated-file-sync-using-circleci" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Automated File Sync Using CircleCI</h3>
|
||
<p>You can automate pulling down and uploading translations for your files using the <a href="https://circleci.com">CircleCI</a> web continuous integration service.</p>
|
||
<p>First, update the <code>circle.yml</code> 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 <code>circle.yml</code> file:</p>
|
||
<pre><code class="hljs css yaml"><span class="hljs-attr">machine:</span>
|
||
<span class="hljs-attr"> node:</span>
|
||
<span class="hljs-attr"> version:</span> <span class="hljs-number">6.10</span><span class="hljs-number">.3</span>
|
||
<span class="hljs-attr"> npm:</span>
|
||
<span class="hljs-attr"> version:</span> <span class="hljs-number">3.10</span><span class="hljs-number">.10</span>
|
||
|
||
<span class="hljs-attr">test:</span>
|
||
<span class="hljs-attr"> override:</span>
|
||
<span class="hljs-bullet"> -</span> <span class="hljs-string">"true"</span>
|
||
|
||
<span class="hljs-attr">deployment:</span>
|
||
<span class="hljs-attr"> website:</span>
|
||
<span class="hljs-attr"> branch:</span> <span class="hljs-string">master</span>
|
||
<span class="hljs-attr"> commands:</span>
|
||
<span class="hljs-comment"># configure git user</span>
|
||
<span class="hljs-bullet"> -</span> <span class="hljs-string">git</span> <span class="hljs-string">config</span> <span class="hljs-bullet">--global</span> <span class="hljs-string">user.email</span> <span class="hljs-string">"test-site-bot@users.noreply.github.com"</span>
|
||
<span class="hljs-bullet"> -</span> <span class="hljs-string">git</span> <span class="hljs-string">config</span> <span class="hljs-bullet">--global</span> <span class="hljs-string">user.name</span> <span class="hljs-string">"Website Deployment Script"</span>
|
||
<span class="hljs-bullet"> -</span> <span class="hljs-string">echo</span> <span class="hljs-string">"machine github.com login test-site-bot password $GITHUB_TOKEN"</span> <span class="hljs-string">> ~/.netrc
|
||
# install Docusaurus and generate file of English strings
|
||
- cd website && npm install && npm 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=test-site-bot npm run publish-gh-pages
|
||
</span></code></pre>
|
||
<p>The <code>crowdin</code> command uses the <code>crowdin.yaml</code> file generated with the <code>examples</code> script. It should be placed in your project directory to configure how and what files are uploaded/downloaded.</p>
|
||
<p>Note that in the <code>crowdin.yaml</code> file, <code>CROWDIN_PROJECT_ID</code> and <code>CROWDIN_API_KEY</code> are environment variables set-up in Circle for your Crowdin project. They can be found in your Crowdin project settings.</p>
|
||
<p>Now, Circle will help you automatically get translations prior to building your website. The provided <code>crowdin.yaml</code> file will copy translated documents into <code>website/translated_docs/</code>, and translated versions of the <code>i18n/en.json</code> strings file will into <code>i18n/${language}.json</code>.</p>
|
||
<p>If you wish to use Crowdin on your machine locally, you can install the <a href="https://support.crowdin.com/cli-tool/">Crowdin CLI tool</a> and run the same commands found in the <code>circle.yaml</code> file. The only difference is that you must set <code>project_identifier</code> and <code>api_key</code> values in the <code>crowdin.yaml</code> file since you will not have Circle environment variables set up.</p>
|
||
<h2><a class="anchor" aria-hidden="true" name="versioned-translations"></a><a href="#versioned-translations" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioned Translations</h2>
|
||
<p>If you wish to have translation and versioning for your documentation, add the following section to the end of your <code>crowdin.yaml</code> file:</p>
|
||
<pre><code class="hljs css yaml"><span class="hljs-bullet"> -</span>
|
||
<span class="hljs-attr"> source:</span> <span class="hljs-string">'/website/versioned_docs/**/*.md'</span>
|
||
<span class="hljs-attr"> translation:</span> <span class="hljs-string">'/website/translated_docs/%locale%/**/%original_file_name%'</span>
|
||
<span class="hljs-attr"> languages_mapping:</span> <span class="hljs-meta">*anchor</span>
|
||
</code></pre>
|
||
<p>Translated, versioned documents will be copied into <code>website/translated_docs/${language}/${version}/</code>.</p>
|
||
<blockquote>
|
||
<p>Ensure in your Crowdin settings, in the Translations section, that "Duplicate Strings" are set to <a href="https://support.crowdin.com/api/create-project/">"Hide - all duplicates will share the same translation"</a>. This setting will ensure that identical strings between versions share a single translation.</p>
|
||
</blockquote>
|
||
</span></div></article></div><div class="docs-prevnext"><a class="docs-prev button" href="navigation.html">← Navigation and Sidebars</a><a class="docs-next button" href="versioning.html">Versioning →</a></div></div></div></div><footer class="nav-footer" id="footer"><section class="sitemap"><a href="/" class="nav-home"><img src="/img/docusaurus_monochrome.svg" alt="Docusaurus" width="66" height="58"/></a><div><h5>Docs</h5><a href="
|
||
/docs/en/installation.html">Getting Started</a><a href="
|
||
/docs/en/versioning.html">Versioning</a><a href="
|
||
/docs/en/translation.html">Localization</a><a href="
|
||
/docs/en/search.html">Adding Search</a></div><div><h5>Community</h5><a href="/en/users.html">User Showcase</a><a href="https://twitter.com/docusaurus">Twitter</a></div><div><h5>More</h5><a href="https://github.com/facebook/docusaurus">GitHub</a><a class="github-button" href="https://github.com/facebook/Docusaurus" data-icon="octicon-star" data-count-href="/facebook/Docusaurus/stargazers" data-count-api="/repos/facebook/Docusaurus#stargazers_count" data-count-aria-label="# stargazers on GitHub" aria-label="Star this project on GitHub">Star</a></div></section><a href="https://code.facebook.com/projects/" target="_blank" class="fbOpenSource"><img src="/img/oss_logo.png" alt="Facebook Open Source" width="170" height="45"/></a><section class="copyright"><span>Copyright © 2017 Facebook Inc.</span></section></footer></div><script type="text/javascript" src="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.js"></script><script>
|
||
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
||
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
||
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
||
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
|
||
|
||
ga('create', 'UA-44373548-31', 'auto');
|
||
ga('send', 'pageview');
|
||
</script><script>window.fbAsyncInit = function() {FB.init({appId:'1615782811974223',xfbml:true,version:'v2.7'});};(function(d, s, id){var js, fjs = d.getElementsByTagName(s)[0];if (d.getElementById(id)) {return;}js = d.createElement(s); js.id = id;js.src = '//connect.facebook.net/en_US/sdk.js';fjs.parentNode.insertBefore(js, fjs);}(document, 'script','facebook-jssdk'));
|
||
</script><script>window.twttr=(function(d,s, id){var js,fjs=d.getElementsByTagName(s)[0],t=window.twttr||{};if(d.getElementById(id))return t;js=d.createElement(s);js.id=id;js.src='https://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js, fjs);t._e = [];t.ready = function(f) {t._e.push(f);};return t;}(document, 'script', 'twitter-wjs'));</script><script>
|
||
var search = docsearch({
|
||
apiKey: '3eb9507824b8be89e7a199ecaa1a9d2c',
|
||
indexName: 'docusaurus',
|
||
inputSelector: '#search_input_react'
|
||
});
|
||
</script></body></html> |