Roadmap: Admin Panel i18n

[jmikrut]

Description

Currently there are many English strings used within Payload's React admin panel. This Roadmap item would see them all replaced and translated into many different languages so that users that do not speak English can still use Payload's admin panel.

Implementation Detail

Here's what will be needed:

1. Build a new React context provider, similar to the existing Theme provider, that lives at the top level of the admin UI and sends down the currently active UI locale through to all components
2. Store the active locale in local storage, exactly like we do with the theme
3. Extend Payload Settings in the Account view with a Select component that allows for the admin to choose which language they want the UI to render in
4. Create an API to store / retrieve all strings requiring translation, either by using something like react-i18next or rolling our own
5. Go through the admin UI and update all instances of hard-coded strings with the new translation API
6. Translate all strings from English to each language that we want to support, adding more over time

Potential Breaking Changes

None

Effort

Medium

[Rar9]

If you provide an open way to translate the admin panel fields, the growing community will be able to help with translations.

[thgh]

Here is how it would look like for contributors when using POEditor as crowdsourcing translation platform: https://poeditor.com/join/project/wG8XpoKUTB

Sidenote: it's best to decide on a naming strategy for translation keys beforehand, e.g. <component>.<key> & <page>.<key>

[christian-reichart]

Could help with the german translation.

Also
7. Ability to set localized labels, descriptions of fields and validation messages
should probably be on the radar.

[arieltonglet]

I can help translate to portuguese (pt-br)

[yagee]

I can help translate to Russian.

[khakimvinh]

I can help translate to Vietnamese

[lucasrabiec]

I can help translate to Polish

[klapec]

me too!

[Julesdj]

I can help with French translation

[Etheliene]

Can help with german as well!

[joeyjurjens]

I could help with Dutch translations :)

[ChrisGV04]

I could help with the Spanish translations

[DanRibbens]

Heroes of our time: @christian-reichart @arieltonglet @yagee @khakimvinh @lucasrabiec @klapec @Julesdj @Etheliene @joeyjurjens @ChrisGV04,
🎉 We are ready for help from the community to get these translations written for all languages! 🎉

What you'll do is:

• Fork the repo.
• Fetch the branch: feat/#300-admin-localization and make a new branch for your translation.
• Copy the en.json translation file found here: https://github.com/payloadcms/payload/tree/feat/%23300-admin-localization/src/translations and name it with the langauge code you are working on. Don't worry about adding your locale to the src/languages/index.ts—we'll avoid conflicts by doing it at the end.
• Translate all the things for your language🥇
• Commit, push and open a PR back to payloadcms/payload/feat/Roadmap: Admin Panel i18n #300-admin-localization branch

See the contributing guide if you have questions https://github.com/payloadcms/payload/blob/master/contributing.md

We'll review and merge them as they appear complete.

When your changes are accepted and merge they will show up in this PR: #1326
If you're coming in after that PR has been merged to master, then you can PR to master.

Did I cover everything?

[DanRibbens]

What's the best way to name a branch for translation?

feat/••-translation would be good but it doesn't really matter. PRs will be squashed and merged.

Thanks!

[thgh]

Did you consider a crowdsourcing translation platform like POEditor?

[thgh]

I imported en.json here and auto-translated to Dutch. It reached the limit when translating the next language, but there is a free plan for open source projects.

[Julesdj]

Just seeing this. Will tackle the French translation right away.

[mitch3s]

I imported en.json here and auto-translated to Dutch. It reached the limit when translating the next language, but there is a free plan for open source projects.

Great initiative. I just updated the Dutch translations as I started translating them manually already. They should make a bit more sense now, as auto-translating can be a bit quirky ("Save" was translated as "Sla" 🙂)

Just opened a PR for it.

[ScottEAdams]

Great to see that you went with react-i18next 💪
How will this work with our own fields? Something like
label: t('collection_name.field_name.whatever')

[DanRibbens]

That is what I'm working on next. My plan is to support objects for labels on collections, globals and fields right in the config.

label: { en: 'Example', es: 'Example', //etc }.

I don't know of another way since there is not a language selected at build time.

Besides field labels, this is what is left on my to-do list:

• select and radio field options
• field placeholder
• field descriptions
• Collection and Globals admin.description
• Collection and Globals admin.group
• Date field (react-datepicker)
• Select field (react-select)
• add i18n-http-middleware to support error responses including field validation functions
• password reset workflow email templates
• dates

I'd also like to add a way for a payload config to override any Payload translations and fallback language.

Hopefully that is everything!

[bombnp]

Hi, I'd love to contribute a Thai translation. I have a few questions though.

1. How do I test my new translations in action? I wanna see them all together to see if they fit, instead of just a list of words in json.
2. Some technical words just sound weird when translated literally in Thai, like Dashboard, API Key, Version (some even are just same English pronunciation just with Thai characters). Is it ok if I just leave some words as English? Most Thai users should be able to understand those technical words anyways.

[DanRibbens]

@bombnp,

To test:

1. Create the translation file
2. Import it in src/languages/index.ts and export it like the others
3. Run one of the dev suites yarn dev admin for example, or any other env from the test directory
4. In the browser, login, then in the account page you should see your added translation:
   

I'd say just do your best and look at the other language PRs for inspiration. I do think leaving some English is expected. For example left in "API URL" in hard-coded for this reason.

[bombnp]

Thanks, @DanRibbens! I'll keep working on it.

[arieltonglet]

Took me a while to realize that the autogenerated ethereal username and password doesn't work with yarn dev admin
So, for anyone trying to login after yarn dev admin, username is [email protected] and password is test

[mustafa-online]

I'm interested in "Arabic". but I wanna know if the dashboard supports RTL?

[DanRibbens]

Oh! I forgot about RTL.

I can make a quick change to set the text direction dynamically based on language selection. You can just focus on the translation file for now.

[mustafa-online]

Not just the text direction but the All aspects of direction.
"Sidebar to the right" for example.

[lucasrabiec]

Wow, gtk. I never made a site in Arabic but always thought it is only a change of text direction.

[mustafa-online]

@lucasrabiec , Yeah everything should start from Right to Left.
Check the BBC Arabic version as an example.

[jacobsfletch]

For anyone just jumping into this thread, RTL is actively being worked on. You can follow along this PR for updates: #3003

[arieltonglet]

Hi @DanRibbens, first of all thanks for setting this up :)
I'm done with my part, but want to check some things before opening a PR:

• I've found some fields that has the same exact value. Maybe it's due to legacy code, but always good to check if this wasn't some copy/paste error. The fields are:
  selectCollection / selectCollectionToBrowse
loggedIn / loginWithAnotherUser

• While testing, I've found some texts that are not being translated. It's the labels and placeholders for search and filters
  
  

[arieltonglet]

No problem, will do that!

[arieltonglet]

Dan, where will "itemsAndMore": "{{items}} and {{count}} more" be used? Couldn't find it.

[DanRibbens]

I've got a lot of changes cooking and so I only pushed the en language file updates for everyone to have quickly. "itemsAndMore" will be plugged into the components:
src/admin/components/views/collections/List/Cell/field-types/Blocks/index.tsx and src/admin/components/views/collections/List/Cell/field-types/Relationship/index.tsx

Sorry for any confusion. I will have everything pushed once I get some tests added and fixed.

[arieltonglet]

No problem at all, @DanRibbens!
I've just merged your latest inclusions to en.json and opened a PR with the translation.
I don't know whats the best workflow for that, but fell free to let me know when you guys add new content to be translated.

[hunghvu]

I feel the same too, and in addition, some fields have fairly vague meanings as there is no context for them. I tried looking at the main branch, but could not have a conclusion. Just to name a few:

// Are they the same? If not, they can be translated differently depending on the context. 
// I tried not to translate word-for-word, except in certain technical contexts. 
// Rather, I prefer to use free translation as they better convey the meaning in my opinion.

"general":  {
  "notFound": "Not Found",
  "nothingFound": "Nothing found" ,
}

"error": {
  "unknown": "An unknown error has occurred.",
  "unspecific": "An error has occurred.",
}

I will keep track of future changes to improve the Vietnamese translation.

[DanRibbens]

A number of translators have pointed out in their PRs that different languages use mascular or feminine contexts. I am weighing now if it is worth addressing this now or punting until later. Part of me says let's address it now, the other part of me says this is scope creep on an already huge feature...

The issue in more detail as @ChrisGV04 said:

I used the male version in all of my translations with dynamic labels, since it's the most common one. However, in the example you mentioned of "Fruits", in Spanish it's translated as "Frutas" which is feminine, so using my initial translations the "Add new fruit" label would be translated into "Añadir nuevo fruta" which is incorrect and should be "Añadir nueva fruta", but for "Cars" which in Spanish is "Carros" in masculine, the label "Add new car" would be translated into "Añadir nuevo carro" which is correct.

The way I would address this on the Payload side would be to add a new property to the collection config for setting the masculinity for translation and pass that context through when calling translations if it was provided and then we need to add those variations to the language files where appropriate.

Is this a deal breaker or a nice to have?

[arieltonglet]

I had the same issue working with the Portuguese translations. I solved it as I often see in many places that need to add this kind of reading possibilities: with slashes (for single letters, articles) and parenthesis (for endings).

In the examples above, it would be "Add new Fruit" / "Adicionar novo(a) Fruta" e "Add new Car" / "Adicionar novo(a) Carro".
In another example, "You are about to delete the {{label}} (...)" would be "Você está prestes a excluir o/a {{label}} (...)" as "the" can be translated to "o" (masculine) or "a" (feminine).

I don't know if there are any languages that lack this kind of feature. But for the cases pointed here, I think this is a good enough solution that is widely adopted and grammatically correct as well

[thgh]

Wordpress solves this by having a separate "Add item" in translations which also solves the case where you want buttons to change the "Add" for a specific custom field, e.g. "Register an item"

[cbrualdi]

@DanRibbens, it's not a big deal for me.
Another possible way to avoid having a double masculine / feminine translation could be to refer to the type of object (collection, document, field, etc..) and not to its name.

Taking noResults as an example, in Italian we would have Nessun {{label}} trovato for the masculine and Nessuna {{label}} trovata for the feminine. But if we know that {{label}} is a document we can write Nessun documento {{label}} trovato (i.e. No {{label}} documents found), which is always masculine.

It may not always be that simple, but we can mitigate the problem a bit.
On the idea of adding a masculinity property, it would be a great finesse, but I would prefer to prioritize extending the admin localization feature as specified here and improve the overall usability of the content localization system (e.g. #1308) as well.

[Arctomachine]

I want to add that masculine/feminine issue is even greater in number of languages, as they have 3rd option referred to as middle (or maybe each language has its own name for it). To my knowledge, this is the case for russian and german. While in russian it only concerns adjectives, in german it also concerns articles.

[mitch3s]

Edit: after checking the PR I noticed this is actually already implemented this way. So this comment can be ignored :)

---

To make things even more complicated, many languages also have different rules for pluralization. See: Unicode Language Plural Rules.
Fortunately it seems that i18next supports this.

This would be not so much for the examples above, but for example the following from the translation file:

    "versionCount_many": "{{count}} versions found",
    "versionCount_none": "No versions found",
    "versionCount_one": "{{count}} version found",

[hunghvu]

I can also help with Vietnamese translation.

[hunghvu]

PR summited: #1346.

[khakimvinh]

You beat me to it 👍

[maekoya]

Great discussion. I created a PR for Japanese translation. #1351

[DanRibbens]

We are working on getting i18n merged this week. If any more language PRs are opened after tomorrow they'll need to change the target to master.

[denolfe]

Released in 1.2.0.