3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-08-03 16:59:06 +02:00
Code Issues Projects Releases Packages Wiki Activity

Deploy website

Browse source 
Deploy website version based on c0723bb095
This commit is contained in:
Website Deployment Script 2018-03-08 19:12:14 +00:00
parent c0723bb095
commit 3f83797433
1 changed files with 38 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

53
docs/en/translation.html
View file

@ -17,11 +17,18 @@
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>
<ul>
<li>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.</li>
</ul>
<blockquote>
<p>Generally, you will use <code>help-with-translations.js</code> 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 <code>help.js</code> and use it as a starting point.</p>
</blockquote>
<ul>
<li><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></li>
<li><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></li>
</ul>
<h2><a class="anchor" aria-hidden="true" id="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>
<p>Your documentation files (e.g., the <code>.md</code> files that live in your <code>docs</code> directory) 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" id="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>
@ -39,9 +46,12 @@ const translate = require("../../server/translate.js").translate;
<span class="xml"><span class="hljs-tag">&lt;<span class="hljs-name">translate</span> <span class="hljs-attr">desc</span>=<span class="hljs-string">"flower, not verb"</span>&gt;</span>Rose<span class="hljs-tag">&lt;/<span class="hljs-name">translate</span>&gt;</span></span>
&lt;p&gt;
</code></pre>
<blockquote>
<p>The <code>&lt;translate&gt;</code> tag generally works well on pure strings. If you have a string like &quot;Docusaurus currently provides support to help your website use <a href="${siteConfig.baseUrl}docs/${this.props.language}/translation.html">translations</a>&quot;, wrapping the <code>&lt;translation&gt;</code> 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 <code>&lt;translate&gt;</code> tags amongst the pure substrings of that string.</p>
</blockquote>
<h2><a class="anchor" aria-hidden="true" id="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>
<p>Add the following script to your <code>website/package.json</code> file, if it does not exist already:</p>
<pre><code class="hljs css json">...
"scripts": {
"write-translations": "docusaurus-write-translations"
@ -71,9 +81,12 @@ const translate = require("../../server/translate.js").translate;
<h2><a class="anchor" aria-hidden="true" id="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 &quot;English&quot; 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>
<p>Ensure in your Crowdin settings, in the Translations section, that &quot;Duplicate Strings&quot; are set to <a href="https://support.crowdin.com/api/create-project/">&quot;Hide - all duplicates will share the same translation&quot;</a>. This setting will ensure that identical strings between versions share a single translation.</p>
</blockquote>
<p>Your project will need a <code>crowdin.yaml</code> file generated. If you ran <code>yarn examples translations</code> or <code>npm run examples translations</code>, this file was created for you on the same level as your <code>website</code> diretory.</p>
<blockquote>
<p>You will need to install the <code>crowdin</code> command line interface. 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>
@ -99,18 +112,31 @@ const translate = require("../../server/translate.js").translate;
<span class="hljs-attr"> 'zh-TW':</span> <span class="hljs-string">'zh-TW'</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" id="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>
<h3><a class="anchor" aria-hidden="true" id="setup-the-crowdin-scripts"></a><a href="#setup-the-crowdin-scripts" 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>Setup the Crowdin Scripts</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"
"crowdin-upload": "export CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID;
export CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY; crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
"crowdin-download": "export CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID;
export CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY; crowdin --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>
<blockquote>
<p><code>YOUR_CROWDIN_PROJECT_ID</code> is the name of your Crowdin project. e.g., for <a href="https://crowdin.com/project/docusaurus/">https://crowdin.com/project/docusaurus/</a>, that variable would be set to <code>docusaurus</code>. <code>YOUR_CROWDIN_API_KEY</code> is a unique key that is like a password. You can find it in the <code>API</code> tab of your Crowdin project's <code>Settings</code>.</p>
</blockquote>
<blockquote>
<p>If you run more than one localized Docusaurus project on your computer, you should change the name of the environment variables to something unique (<code>CROWDIN_PROJECTNAME_PROJECT_ID</code>, <code>CROWDIN_PROJECTNAME_API_KEY</code>).</p>
</blockquote>
<h3><a class="anchor" aria-hidden="true" id="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 always want to upload your markdown files and translatable strings first and the download the translations section. So run the commands in this order:</p>
<pre><code class="hljs">yarn <span class="hljs-keyword">run</span><span class="bash"> crowdin-upload
</span>yarn <span class="hljs-keyword">run</span><span class="bash"> crowdin-download
</span></code></pre>
<blockquote>
<p>Since the files are generated, you do not need to have any files in your <code>website/i18n</code> or <code>website/translated_docs</code> directory as part of your repo. So you can can add <code>website/i18n/*</code> and <code>website/translated_docs</code> to your <code>.gitignore</code> file.</p>
</blockquote>
<h3><a class="anchor" aria-hidden="true" id="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>
@ -156,9 +182,6 @@ const translate = require("../../server/translate.js").translate;
<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 &quot;Duplicate Strings&quot; are set to <a href="https://support.crowdin.com/api/create-project/">&quot;Hide - all duplicates will share the same translation&quot;</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="