diff --git a/website-1.x/blog/2021-03-09-releasing-docusaurus-i18n.md b/website-1.x/blog/2021-03-09-releasing-docusaurus-i18n.md new file mode 100644 index 000000000000..6f95aa3381fd --- /dev/null +++ b/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)! + + + +## 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. diff --git a/website-1.x/static/img/blog/2021-03-09-releasing-docusaurus-i18n/datagit.png b/website-1.x/static/img/blog/2021-03-09-releasing-docusaurus-i18n/datagit.png new file mode 100644 index 000000000000..4a0ed09c6e81 Binary files /dev/null and b/website-1.x/static/img/blog/2021-03-09-releasing-docusaurus-i18n/datagit.png differ diff --git a/website-1.x/static/img/blog/2021-03-09-releasing-docusaurus-i18n/jest.png b/website-1.x/static/img/blog/2021-03-09-releasing-docusaurus-i18n/jest.png new file mode 100644 index 000000000000..bcb903a7fbdb Binary files /dev/null and b/website-1.x/static/img/blog/2021-03-09-releasing-docusaurus-i18n/jest.png differ diff --git a/website-1.x/static/img/blog/2021-03-09-releasing-docusaurus-i18n/redwood.png b/website-1.x/static/img/blog/2021-03-09-releasing-docusaurus-i18n/redwood.png new file mode 100644 index 000000000000..a1a2a2a1fe43 Binary files /dev/null and b/website-1.x/static/img/blog/2021-03-09-releasing-docusaurus-i18n/redwood.png differ diff --git a/website-1.x/static/img/blog/2021-03-09-releasing-docusaurus-i18n/social-card.png b/website-1.x/static/img/blog/2021-03-09-releasing-docusaurus-i18n/social-card.png new file mode 100644 index 000000000000..9d8f46cd3498 Binary files /dev/null and b/website-1.x/static/img/blog/2021-03-09-releasing-docusaurus-i18n/social-card.png differ diff --git a/website/docs/i18n/i18n-introduction.md b/website/docs/i18n/i18n-introduction.md index 51e55991bf91..5043b1990dcf 100644 --- a/website/docs/i18n/i18n-introduction.md +++ b/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: diff --git a/website/static/img/blog/2021-03-09-releasing-docusaurus-i18n/datagit.png b/website/static/img/blog/2021-03-09-releasing-docusaurus-i18n/datagit.png new file mode 100644 index 000000000000..4a0ed09c6e81 Binary files /dev/null and b/website/static/img/blog/2021-03-09-releasing-docusaurus-i18n/datagit.png differ diff --git a/website/static/img/blog/2021-03-09-releasing-docusaurus-i18n/jest.png b/website/static/img/blog/2021-03-09-releasing-docusaurus-i18n/jest.png new file mode 100644 index 000000000000..bcb903a7fbdb Binary files /dev/null and b/website/static/img/blog/2021-03-09-releasing-docusaurus-i18n/jest.png differ diff --git a/website/static/img/blog/2021-03-09-releasing-docusaurus-i18n/redwood.png b/website/static/img/blog/2021-03-09-releasing-docusaurus-i18n/redwood.png new file mode 100644 index 000000000000..a1a2a2a1fe43 Binary files /dev/null and b/website/static/img/blog/2021-03-09-releasing-docusaurus-i18n/redwood.png differ diff --git a/website/static/img/blog/2021-03-09-releasing-docusaurus-i18n/social-card.png b/website/static/img/blog/2021-03-09-releasing-docusaurus-i18n/social-card.png new file mode 100644 index 000000000000..9d8f46cd3498 Binary files /dev/null and b/website/static/img/blog/2021-03-09-releasing-docusaurus-i18n/social-card.png differ