search

facebook / docusaurus

Easy to maintain open source documentation websites.
https://docusaurus.io
MIT License
55.94k stars 8.39k forks source link

Help us translate the Docusaurus website #3526

Open slorber opened 4 years ago

slorber commented 4 years ago

Last updated: 05/10/2023

Help us translate the Docusaurus 2 website

The Docusaurus 2 i18n support is ready, and it's time for Docusaurus 2 website to be translated

This issue is here to organize the translation effort.

Translation process

Theme default translations

The classic theme ships with some default translation bundles for theme labels, like "next" / "previous" pagination buttons...

Please help us provide/complete/double-check the default theme label translations for your own language: https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-translations/locales

Existing language

If your language already exists in the folder above, please edit the files with completed or more accurate translations.

New language

If your language does not exist, you will need to create it from scratch.

You have 2 options:

In most cases, use a simple language code like fr or es for <newLanguage>, and use locales such as pt-BR and pt-PT when the difference between the 2 variants is strong enough.

Use appropriate pluralization

Note: some languages have complex plural rules. Make sure the pluralized labels (containing a |) contain as many variants as your locale has plural rules (number of cardinal categories).

Run this code in your browser to obtain the plural forms of any locale/language:

function getLocalePluralForms(locale) {
  const AllPluralForms = ['zero','one','two','few','many','other']
  const pluralCategories = new Intl.PluralRules(locale).resolvedOptions().pluralCategories;
  pluralCategories.sort((c1,c2) => AllPluralForms.indexOf(c1) > AllPluralForms.indexOf(c2) ? 1 : -1);
  return pluralCategories;
}

const myLocale = "fr"; // Change this variable!
console.log("Plural forms for this locale are =>>> ",getLocalePluralForms(myLocale));

Note: the order of plural forms in the translation string matters.

Files to translate on Crowdin

Please translate in priority:

Please be careful for:

Please do not translate for now:

Preview your translation work

Unfortunately, it is not possible for you to test the translated site locally (the Crowdin auth system is not very flexible)

If you are actively working on a locale, please ask to add that locale to our i18n staging deployment:

Please translate at least 10% before asking for enabling your locale in this staging deployment.

Production

We ask for a minimal amount of translations to be reached:

Once a locale has enough translations, and the preview looks good on the i18n staging environment, we'll add it to our production site.

Thanks for your help 😃

slorber commented 3 years ago

Thanks a lot @rafaelbmateus ! I'll enable the pt-BR locale in our staging env asap, just busy finishing things for a release but it will be done very soon!

massoudmaboudi commented 3 years ago

@slorber @lex111 I would appreciate it if you could enable Farsi (fa-IR) translation to start the translation. Please consider that when a user chooses to use Farsi, the style should also change from LTR to RTL.

slorber commented 3 years ago

Thanks @massoudmaboudi , just enabled Farsi here: https://crowdin.com/project/docusaurus-v2/fa Will enable it on our staging env once 10% translations were submitted.

Please consider that when a user chooses to use Farsi, the style should also change from LTR to RTL.

Yes, this is applied automatically by Docusaurus as Intl apis can tell us language direction for a language/locale code.

massoudmaboudi commented 3 years ago

Thanks @massoudmaboudi , just enabled Farsi here: https://crowdin.com/project/docusaurus-v2/fa Will enable it on our staging env once 10% translations were submitted.

Please consider that when a user chooses to use Farsi, the style should also change from LTR to RTL.

Yes, this is applied automatically by Docusaurus as Intl apis can tell us language direction for a language/locale code.

Thank you @slorber. I will inform you when the translation happens.

slorber commented 3 years ago

We have merged 2 new translation keys (in https://github.com/facebook/docusaurus/pull/3646, feature visible here: https://docusaurus.io/tests/docs/)

Please help us translate those new keys:

"theme.docs.tagDocListPageTitle": "{nDocsTagged} with \"{tagName}\"",
"theme.docs.tagDocListPageTitle___DESCRIPTION": "The title of the page for a docs tag",

"theme.docs.tagDocListPageTitle.nDocsTagged": "One doc tagged|{count} docs tagged",
"theme.docs.tagDocListPageTitle.nDocsTagged___DESCRIPTION": "Pluralized label for \"{count} docs tagged\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)",
supernover commented 3 years ago

i would like to help out,if you could enable Kinyarwanda (eng-ki) thanks!

slorber commented 3 years ago

Thanks @supernover , enabled it here: https://crowdin.com/project/docusaurus-v2/rw

hanancs commented 3 years ago

Hi @slorber, I can help with Tamil. Thanks

slorber commented 3 years ago

Thanks, Tamil is now enabled @hanancs https://crowdin.com/project/docusaurus-v2/ta

caleeli commented 3 years ago

Hi! I can help with Spanish translations.

MrTechHunter commented 3 years ago

Hey! I can help with Persian/Farsi which is Iranian language.

lex111 commented 3 years ago

For those who want to contribute with code, you can help translate our classic theme by adding new or improving existing translation. For more details, please see this section https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/codeTranslations#for-docusaurus-users

MrTechHunter commented 3 years ago

Hey mate @lex111 This is my PR: https://github.com/facebook/docusaurus/pull/5640

Sincerely, Mahdi Hamldar

uguraktas commented 2 years ago

hey, @slorber I am happy to help with Turkish translation.

slorber commented 2 years ago

Thanks @uguraktas

It's not necessary to tell us there, you can directly submit your translations on Crowdin (https://crowdin.com/project/docusaurus-v2/tr) and I'll enable a Turkish site once enough translations have been submitted

jrmejiaa commented 2 years ago

Hi @slorber I would like to help with Spanish, I saw that there are just 4% of the page translated. However, I don't have much time, so could you tell me which pages are the more important ones in order to have a first Spanish version of docusaurus?

slorber commented 2 years ago

FYI the default theme translations have been moved to a new package: https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-translations

I edited the issue to reflect this change

slorber commented 2 years ago

@jrmejiaa this issue is up-to-date and all the relevant info are displayed at the top. Unfortunately navigating a i18n site that is only half translated is not very nice for the users. If we could get at least the getting started + guides in Spanish, that would be nice

noomorph commented 2 years ago
  • ~Slave~ languages, 4 plural forms: "One post|Few posts|Many posts|{count} posts"

It is rude and unpleasant to see. 🤦‍♂️ Please fix to Slavic whenever you can.

ss-o commented 2 years ago

Hey @slorber,

I recently adopted Docusaurus for my projects. While having the learning curve I can kick off Lithuanian translations, at the same time would be a great practice for me. If there are no limits on how small :mag: a country can be for translations :wink:

slorber commented 2 years ago

Thanks @ss-o 👍 , you can now translate our site to lt here: https://crowdin.com/project/docusaurus-v2/lt

zixuan945 commented 2 years ago

Some snippets like <code>'light' \| 'dark'</code> is not escaped correctly and becomes garbage characters on the pages in other languages, looking like! !crwdBlockTags_299_sgaTkcolBdwrc!!! image image

Josh-Cena commented 2 years ago

@zixuan945 This is a known bug with Crowdin. See #5602

slorber commented 2 years ago

Admonition default titles are now translatable (https://github.com/facebook/docusaurus/pull/7556) (canary or next release)

Please help us and provide the missing admonition translations for your language: https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-translations/locales

(tip: also provide all the other missing translations at the same time)

CarlosMarinAquino commented 1 year ago

I want to collab in the Spanish version, did you have one branch for this language?

SilverTee commented 1 year ago

I want to collab in the Spanish version, did you have one branch for this language?

you could do this here: https://crowdin.com/project/docusaurus-v2/es-ES

shawshankkumar commented 1 year ago

Hey @slorber is there a chance https://docusaurus-i18n-staging.netlify.app/ this isn't auto updating? because I don's see a few things on the production link here. Also, I'd like to contribute to Hindi, anything I should be aware of?

slorber commented 1 year ago

There's a section in our "Preview your translation work" that explains how this preview work. It is supposed to be up to date (but sometimes fail, not a big deal). Last successful publish was yesterday. I don't know what you are looking for that you don't find so it's hard to say if there's a problem or not.

Nothing particular to do to contribute to Hindi apart reading the docs. If you have any question left after reading that doc and giving it a try, I'll answer them.

shawshankkumar commented 1 year ago

Thanks I'll give it a try!

On Thu, Dec 15, 2022 at 8:34 PM Sébastien Lorber @.***> wrote:

There's a section in our "Preview your translation work" that explains how this preview work. It is supposed to be up to date (but sometimes fail, not a big deal). Last successful publish was yesterday. I don't know what you are looking for that you don't find so it's hard to say if there's a problem or not.

Nothing particular to do to contribute to Hindi apart reading the docs. If you have any question left after reading that doc and giving it a try, I'll answer them.

— Reply to this email directly, view it on GitHub https://github.com/facebook/docusaurus/issues/3526#issuecomment-1353232523, or unsubscribe https://github.com/notifications/unsubscribe-auth/AR22P3MZMNWXKPK2QWB2R4DWNMXPTANCNFSM4SBW5NKQ . You are receiving this because you commented.Message ID: @.***>

kgolubic commented 1 year ago

@slorber I'd like to help with the translation of localization and translation of Docusarus to Croatian. It is not available as theme default translations at the moment. What can be done so that I can start with the translation process?

slorber commented 1 year ago

@kgolubic I've clarified the instructions, to create a new theme language in the issue. We have a CLI for that. Please let me know if anything is still unclear.

slorber commented 1 year ago

We are experiencing some issues with Crowdin for all newly uploaded .mdx files.

Notably, the newly released version 2.4.0 has lost its previously existing translations

CleanShot 2023-03-24 at 16 19 38@2x

I hope we'll be able to fix this soon with Crowdin support.

In the meantime, it's probably not worth investing your time in translating these new strings from v2.4.

More info here: https://github.com/facebook/docusaurus/discussions/8821

tyzion commented 1 year ago

hey italian guy here! Could help with italian translation!

tats-u commented 1 year ago

Japanese now meets all the criteria.

P.S. Can't we translate the banner string "⭐️ If you like Docusaurus, give it a star on GitHub and follow us on Twitter" at the top of each page?

slorber commented 1 year ago

Thanks for your work on this @tats-u

Due to recent changes on Crowdin and Netlify I have to adjust a bit our translation workflows and versioning archive procedure, so it's not a great timing right now to enable a new language, but we'll do this when I figure it out.

CarlosMarinAquino commented 1 year ago

Recently I was working in the Spanish version but I can understand how the platform works in some strings shows 1/2 and then turns into 1/163. I attending the transition as long I can

slorber commented 1 year ago

some strings shows 1/2 and then turns into 1/163.

@CarlosMarinAquino I don't understand what you mean here 😅 screenshot?

Zubiii333 commented 1 year ago

I'm working on Bangla localization. Could you please let me know how do I push the changes to test app? @slorber

slorber commented 1 year ago

@Zubiii333 by Bangla you mean Bengali / bn right?

As explained in the intro post, you can't test it locally, and we ask you to first translate at least 10% on Crowdin before turning your local on in our preview environment. Currently Bengali is at 0% translated: https://crowdin.com/project/docusaurus-v2/bn

tats-u commented 1 year ago

The build of https://docusaurus-i18n-staging.netlify.app/ has been broken for a long time, hasn't it?

yuxxeun commented 1 year ago

The build of https://docusaurus-i18n-staging.netlify.app/ has been broken for a long time, hasn't it?

it seems working-well currently, i've visiting it by now

tats-u commented 1 year ago

@yuxxeun It's too old. The latest version there is RC of 2.0. It shows the build has failed for a very long time. If it succeeded, the latest version there would be much newer (e.g. 2.4.x).

slorber commented 1 year ago

The build of docusaurus-i18n-staging.netlify.app has been broken

Yes.

Fixing an issue that prevents the build to even start: https://github.com/facebook/docusaurus/pull/9374

for a long time, hasn't it?

What's the point here?

The build logs are public: https://app.netlify.com/sites/docusaurus-i18n-staging/deploys

The project is open-source and you can submit a PR or translation fixes if you see it failing, or kindly report them if we didn't notice.

Even with my PR above, I'm not sure it will fix every issues, we'll see. It's not my top priority to fix this deployment right now: shipping v3 is way more important.

Edit, apparently no translation problem and i18n staging is now able to build again: https://docusaurus-i18n-staging.netlify.app/

tats-u commented 1 year ago

@slorber It's just because it was too difficult and expected to take too much time for me to specify the trouble spot from the error logs. I never expected that spot to be the culprit. Thanks a lot for fixing the issue on behalf of me.

tats-u commented 11 months ago

Some languages are better translated than Japanese. How about adding them to the staging site?

slorber commented 11 months ago

Some languages are better translated than Japanese. How about adding them to the staging site?

There's a cost for me to adding any language in terms of maintenance (when i18n staging is blocked due to a bad translation, happens often and hard to debug) and adding languages can also add time to the CI builds (and we are already close to the max build time on Netlify).

Unless they request it, until I find a solution to these problems I am cautious when adding new languages, in both prod and staging.

For example if I release v3.0, I don't want the prod deployment to be stuck due to having added a new language in staging just before. This is the kind of risk we encounter right now with the current setup.

paraskevasleivadaros commented 6 months ago

I am excited to inform you that I have commenced work on the Greek translation for the project. I will be actively updating my progress on Crowdin and look forward to contributing to making Docusaurus more accessible to Greek-speaking users. I'll provide updates and reach out if I encounter any issues or need further guidance!

ilmedova commented 4 months ago

@slorber Hi! I would really love to contribute and help with Turkmen language (tm) 🙋🏻‍♀️ It is not available in Crowdin 😞

tats-u commented 4 months ago

@ilmedova Did you mean tk? It looks like it's supported by Crowdin.

https://developer.crowdin.com/language-codes/

ilmedova commented 4 months ago

@tats-u got it, thanks