<!DOCTYPE html><htmllang="en"><head><metacharSet="utf-8"/><metahttp-equiv="X-UA-Compatible"content="IE=edge"/><title>Releasing Docusaurus i18n · Docusaurus</title><metaname="viewport"content="width=device-width, initial-scale=1.0"/><metaname="generator"content="Docusaurus"/><metaname="description"content="Today, we officially release **[Docusaurus 2 i18n](https://v2.docusaurus.io/docs/i18n/introduction)** ([internationalization](https://en.wikipedia.org/wiki/Internationalization_and_localization)), as part of [2.0.0-alpha.71](https://github.com/facebook/docusaurus/releases/tag/v2.0.0-alpha.71)."/><metaname="docsearch:language"content="en"/><metaproperty="og:title"content="Releasing Docusaurus i18n · Docusaurus"/><metaproperty="og:type"content="website"/><metaproperty="og:url"content="https://docusaurus.io/blog/2021/03/09/releasing-docusaurus-i18n"/><metaproperty="og:description"content="Today, we officially release **[Docusaurus 2 i18n](https://v2.docusaurus.io/docs/i18n/introduction)** ([internationalization](https://en.wikipedia.org/wiki/Internationalization_and_localization)), as part of [2.0.0-alpha.71](https://github.com/facebook/docusaurus/releases/tag/v2.0.0-alpha.71)."/><metaproperty="og:image"content="https://docusaurus.io/img/docusaurus.png"/><metaname="twitter:card"content="summary"/><metaname="twitter:image"content="https://docusaurus.io/img/docusaurus.png"/><linkrel="shortcut icon"href="/img/docusaurus.ico"/><linkrel="stylesheet"href="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css"/><linkrel="stylesheet"href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/atom-one-dark.min.css"/><linkrel="alternate"type="application/atom+xml"href="https://docusaurus.io/blog/atom.xml"title="Docusaurus Blog ATOM Feed"/><linkrel="alternate"type="application/rss+xml"href="https://docusaurus.io/blog/feed.xml"title="Docusaurus Blog RSS Feed"/><script>
function createToggler(togglerSelector, targetSelector, className) {
var toggler = document.querySelector(togglerSelector);
var target = document.querySelector(targetSelector);
if (!toggler) {
return;
}
toggler.onclick = function(event) {
event.preventDefault();
target.classList.toggle(className);
};
}
});
</script></nav></div><divclass="container mainContainer postContainer blogContainer"><divclass="wrapper"><divclass="lonePost"><divclass="post"><headerclass="postHeader"><h1class="postHeaderTitle"><ahref="/blog/2021/03/09/releasing-docusaurus-i18n">Releasing Docusaurus i18n</a></h1><pclass="post-meta">March 9, 2021</p><divclass="authorBlock"><pclass="post-authorName"><ahref="https://sebastienlorber.com"target="_blank"rel="noreferrer noopener">Sébastien Lorber</a>Docusaurus maintainer</p><divclass="authorPhoto authorPhotoBig"><ahref="https://sebastienlorber.com"target="_blank"rel="noreferrer noopener"><imgsrc="https://github.com/slorber.png"alt="Sébastien Lorber"/></a></div></div></header><div><span><p>Today, we officially release <strong><ahref="https://v2.docusaurus.io/docs/i18n/introduction">Docusaurus 2 i18n</a></strong> (<ahref="https://en.wikipedia.org/wiki/Internationalization_and_localization">internationalization</a>), as part of <ahref="https://github.com/facebook/docusaurus/releases/tag/v2.0.0-alpha.71">2.0.0-alpha.71</a>.</p>
<p>Docusaurus 2 has now reached <strong>full feature parity with Docusaurus 1</strong>. 🎉 And soon, after a few additional infrastructure updates and a bit more testing, the <strong>first Docusaurus 2 beta</strong> will be released.</p>
<p><strong>We went the extra mile</strong>, and the new i18n support is <strong>even better than in Docusaurus 1</strong>.</p>
<p>In this post, we will present you the <strong>translation workflow</strong>, explain some <strong>design decisions</strong> and <strong>showcase early adopter sites</strong> that just went live: <ahref="https://jestjs.io/">Jest</a>, <ahref="https://learn.redwoodjs.com/">Redwood</a>, and <ahref="https://datagit.ir/">Datagit</a>.</p>
<p>We also <strong>dogfood</strong> the i18n support on the <strong>Docusaurus 2 site itself</strong>, and this post is already available in <ahref="https://v2.docusaurus.io/blog/2021/03/09/releasing-docusaurus-i18n">English</a> and <ahref="https://v2.docusaurus.io/fr/blog/2021/03/09/releasing-docusaurus-i18n">French</a>!</p>
<p>You can translate a Docusaurus site in <strong>3 simple steps</strong>:</p>
<ol>
<li><strong>Configure</strong>: declare the default locale and alternative locales in <code>docusaurus.config.js</code></li>
<li><strong>Translate</strong>: put the translation files at the <ahref="https://v2.docusaurus.io/docs/next/i18n/introduction#translation-files-location">correct filesystem location</a></li>
<li><strong>Deploy</strong>: build and deploy your site using a single or multi-domain strategy</li>
</ol>
<p>The i18n support is <strong>very flexible</strong> and based on the <strong>filesystem</strong>.</p>
<p>The <strong><ahref="https://v2.docusaurus.io/docs/i18n/tutorial">i18n tutorial</a></strong> is the best way to get started, and we provide help to use <strong><ahref="https://v2.docusaurus.io/docs/i18n/git">Git</a></strong> or <strong><ahref="https://v2.docusaurus.io/docs/i18n/crowdin">Crowdin</a></strong>.</p>
<p>The goals of the Docusaurus i18n system are:</p>
<ul>
<li><strong>Simple</strong>: just put the translated files in the <ahref="https://v2.docusaurus.io/docs/next/i18n/introduction#translation-files-location">correct filesystem location</a></li>
<li><strong>Flexible translation workflows</strong>: use Git (monorepo, forks, or submodules), SaaS software, FTP</li>
<li><strong>Flexible deployment options</strong>: single, multiple domains, or hybrid</li>
<li><strong>Modular</strong>: allow plugin authors to provide i18n support</li>
<li><strong>Low-overhead runtime</strong>: documentation is mostly static and does not require a heavy JS library or polyfills</li>
<li><strong>Scalable build-times</strong>: allow building and deploying localized sites independently</li>
<li><strong>Localize assets</strong>: an image of your site might contain text that should be translated</li>
<li><strong>No coupling</strong>: not forced to use any SaaS, yet integrations are possible</li>
<li><strong>Easy to use with <ahref="https://crowdin.com/">Crowdin</a></strong>: multiple Docusaurus 1 sites use Crowdin, and should be able to migrate to v2</li>
<li><strong>Good SEO defaults</strong>: we set useful SEO headers like <ahref="https://developers.google.com/search/docs/advanced/crawling/localized-versions"><code>hreflang</code></a> for you</li>
<li><strong>RTL support</strong>: locales reading right-to-left (Arabic, Hebrew, etc.) are supported and easy to implement</li>
<li><strong>Default translations</strong>: classic theme labels are translated for you in <ahref="https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations">many languages</a></li>
<p>We have made it possible to <strong>upgrade</strong> a <strong>translated Docusaurus 1 site</strong> to Docusaurus 2.</p>
<p><strong><ahref="https://jestjs.io">Jest</a></strong>, using Docusaurus 1 and Crowdin was one of those sites.</p>
<p>The Docusaurus 2 migration was successful and the new site is now deployed in production (<ahref="https://jestjs.io/blog/2021/03/09/jest-website-upgrade">announcement post</a>).</p>
<p><ahref="https://redwoodjs.com/">Redwood</a> is a React full-stack Jamstack framework.</p>
<p>They were looking for a solution to create an <strong>internationalized learning platform</strong>, and became early adopters of Docusaurus 2 i18n for <ahref="https://learn.redwoodjs.com/">learn.redwoodjs.com</a>, using Crowdin to get it translated to French.</p>
<p>The i18n system should work with any language, including <strong>Right-to-Left languages</strong>.</p>
<p><ahref="https://datagit.ir/">Datagit.ir</a> is using Farsi, and a simple configuration option is able to <strong>flip the Docusaurus theme</strong> to add the required Right-to-Left support.</p>
<p>🙏 And please, add your brand new i18n sites to our <ahref="https://v2.docusaurus.io/showcase">showcase page</a>. We accept any all polished Docusaurus site here, and we are working on a <ahref="https://github.com/facebook/docusaurus/issues/4238">redesign</a> allowing you to filter sites by features.</p>
