docs(v2): releasing i18n blog post

website-1.x/blog/2021-03-09-releasing-docusaurus-i18n.md

@@ -0,0 +1,98 @@
+---
+title: Releasing Docusaurus i18n
+author: Sébastien Lorber
+authorTitle: Docusaurus maintainer
+authorURL: https://sebastienlorber.com
+authorImageURL: https://github.com/slorber.png
+authorTwitter: sebastienlorber
+tags: [release, i18n]
+image: /img/blog/2021-03-09-releasing-docusaurus-i18n/social-card.png
+---
+
+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).
+
+Docusaurus 2 has now reached **full feature parity with Docusaurus 1**. 🎉 And soon, after a few additional infrastructure updates and a bit more testing, the **first Docusaurus 2 beta** will be released.
+
+**We went the extra mile**, and the new i18n support is **even better than in Docusaurus 1**.
+
+In this post, we will present you the **translation workflow**, explain some **design decisions** and **showcase early adopter sites** that just went live: [Jest](https://jestjs.io/), [Redwood](https://learn.redwoodjs.com/), and [Datagit](https://datagit.ir/).
+
+We also **dogfood** the i18n support on the **Docusaurus 2 site itself**, and this post is already available in [English](https://v2.docusaurus.io/blog/2021/03/09/releasing-docusaurus-i18n) and [French](https://v2.docusaurus.io/fr/blog/2021/03/09/releasing-docusaurus-i18n)!
+
+<!--truncate-->
+
+## Translate your site
+
+You can translate a Docusaurus site in **3 simple steps**:
+
+1. **Configure**: declare the default locale and alternative locales in `docusaurus.config.js`
+1. **Translate**: put the translation files at the [correct filesystem location](https://v2.docusaurus.io/docs/next/i18n/introduction#translation-files-location)
+1. **Deploy**: build and deploy your site using a single or multi-domain strategy
+
+The i18n support is **very flexible** and based on the **filesystem**.
+
+The **[i18n tutorial](https://v2.docusaurus.io/docs/i18n/tutorial)** is the best way to get started, and we provide help to use **[Git](https://v2.docusaurus.io/docs/i18n/git)** or **[Crowdin](https://v2.docusaurus.io/docs/i18n/crowdin)**.
+
+## Design decisions
+
+The goals of the Docusaurus i18n system are:
+
+- **Simple**: just put the translated files in the [correct filesystem location](https://v2.docusaurus.io/docs/next/i18n/introduction#translation-files-location)
+- **Flexible translation workflows**: use Git (monorepo, forks, or submodules), SaaS software, FTP
+- **Flexible deployment options**: single, multiple domains, or hybrid
+- **Modular**: allow plugin authors to provide i18n support
+- **Low-overhead runtime**: documentation is mostly static and does not require a heavy JS library or polyfills
+- **Scalable build-times**: allow building and deploying localized sites independently
+- **Localize assets**: an image of your site might contain text that should be translated
+- **No coupling**: not forced to use any SaaS, yet integrations are possible
+- **Easy to use with [Crowdin](https://crowdin.com/)**: multiple Docusaurus 1 sites use Crowdin, and should be able to migrate to v2
+- **Good SEO defaults**: we set useful SEO headers like [`hreflang`](https://developers.google.com/search/docs/advanced/crawling/localized-versions) for you
+- **RTL support**: locales reading right-to-left (Arabic, Hebrew, etc.) are supported and easy to implement
+- **Default translations**: classic theme labels are translated for you in [many languages](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations)
+
+## Showcase
+
+We worked with a few volunteers to **dogfood the i18n support** before releasing it.
+
+### Jest: upgrading Docusaurus
+
+We have made it possible to **upgrade** a **translated Docusaurus 1 site** to Docusaurus 2.
+
+**[Jest](https://jestjs.io)**, using Docusaurus 1 and Crowdin was one of those sites.
+
+The Docusaurus 2 migration was successful and the new site is now deployed in production ([announcement post](https://jestjs.io/blog/2021/03/09/jest-website-upgrade)).
+
+[![Jest i18n screenshot](/img/blog/2021-03-09-releasing-docusaurus-i18n/jest.png)](https://jestjs.io)
+
+### Redwood: adopting Docusaurus
+
+[Redwood](https://redwoodjs.com/) is a React full-stack Jamstack framework.
+
+They were looking for a solution to create an **internationalized learning platform**, and became early adopters of Docusaurus 2 i18n for [learn.redwoodjs.com](https://learn.redwoodjs.com/), using Crowdin to get it translated to French.
+
+[![Redwood i18n screenshot](/img/blog/2021-03-09-releasing-docusaurus-i18n/redwood.png)](https://learn.redwoodjs.com/)
+
+### Datagit: using LTR support
+
+The i18n system should work with any language, including **Right-to-Left languages**.
+
+[Datagit.ir](https://datagit.ir/) is using Farsi, and a simple configuration option is able to **flip the Docusaurus theme** to add the required Right-to-Left support.
+
+[![Datagit i18n screenshot](/img/blog/2021-03-09-releasing-docusaurus-i18n/datagit.png)](https://datagit.ir/)
+
+## Conclusion
+
+We sincerely hope you will adopt and like the new i18n support.
+
+This feature has not been an easy one, and we would like to thank everyone that got involved in this journey:
+
+- [Alexey](https://github.com/lex111) for his help to make the i18n support exhaustive and even better than v1
+- [Simen](https://github.com/SimenB) for volunteering and supporting the Jest migration
+- [Claire](https://github.com/clairefro) for adopting Docusaurus 2 on the new Redwood platform and providing many feedbacks
+- [Massoud](https://github.com/massoudmaboudi) for reviewing my work on LTR and adopting it on Datagit
+- [Crowdin](https://crowdin.com/) for their support and willingness to improve their translation SaaS
+- The Docusaurus community for their patience, and providing many useful feedbacks on Github
+
+Thanks for reading.
+
+🙏 And please, add your brand new i18n sites to our [showcase page](https://v2.docusaurus.io/showcase). We accept any Docusaurus site here, and we are working on a [redesign](https://github.com/facebook/docusaurus/issues/4238) allowing you to filter sites by features.

website/docs/i18n/i18n-introduction.md

@@ -23,18 +23,18 @@ For more context, you can read the initial [RFC](https://github.com/facebook/doc
 
 The goals of the Docusaurus i18n system are:
 
-- **Simple**: just put the translated files in the correct file-system location
-- **Flexible translation workflows**: based on Git (monorepo, forks or submodules), SaaS software, FTP
-- **Flexible deployment options**: single or multiple domains
-- **Modular**: allow plugin author to provide i18n support
+- **Simple**: just put the translated files in the correct filesystem location
+- **Flexible translation workflows**: use Git (monorepo, forks, or submodules), SaaS software, FTP
+- **Flexible deployment options**: single, multiple domains, or hybrid
+- **Modular**: allow plugin authors to provide i18n support
 - **Low-overhead runtime**: documentation is mostly static and does not require a heavy JS library or polyfills
-- **Acceptable build-times**: allow building and deploying localized sites independently
+- **Scalable build-times**: allow building and deploying localized sites independently
 - **Localize assets**: an image of your site might contain text that should be translated
-- **No coupling**: not forced to use any SaaS, yet the integration is possible
+- **No coupling**: not forced to use any SaaS, yet integrations are possible
 - **Easy to use with [Crowdin](https://crowdin.com/)**: multiple Docusaurus v1 sites use Crowdin, and should be able to migrate to v2
-- **Good SEO defaults**: setting useful SEO headers like [`hreflang`](https://developers.google.com/search/docs/advanced/crawling/localized-versions) for you
-- **RTL support**: locales reading right-to-left (Arabic, Hebrew, etc.) should be easy to use
-- **Default translations**: classic theme labels are translated for you in [many languages](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations).
+- **Good SEO defaults**: we set useful SEO headers like [`hreflang`](https://developers.google.com/search/docs/advanced/crawling/localized-versions) for you
+- **RTL support**: locales reading right-to-left (Arabic, Hebrew, etc.) are supported and easy to implement
+- **Default translations**: classic theme labels are translated for you in [many languages](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations)
 
 ### i18n non-goals
 
@@ -50,9 +50,9 @@ We don't provide support for:
 
 Overview of the workflow to create a translated Docusaurus website:
 
-- **Configure**: declare the default locale and alternative locales in `docusaurus.config.js`
-- **Translate**: put the translation files at the correct file-system location
-- **Deploy**: build and deploy your site using a single or multi-domain strategy
+1. **Configure**: declare the default locale and alternative locales in `docusaurus.config.js`
+1. **Translate**: put the translation files at the correct filesystem location
+1. **Deploy**: build and deploy your site using a single or multi-domain strategy
 
 ### Translation files
 
@@ -94,7 +94,7 @@ The choice was made for 2 reasons:
 
 ### Translation files location
 
-The translation files should be created at the correct file-system location.
+The translation files should be created at the correct filesystem location.
 
 Each locale and plugin has its own `i18n` subfolder: