Skip to content

Latest commit

 

History

History
152 lines (98 loc) · 8.62 KB

LOCALIZATION.md

File metadata and controls

152 lines (98 loc) · 8.62 KB
Raw

Localization

Now that the first version of the cloud native glossary is live, we'd love to start localizing it into different languages.

Contributions to improving the following localization guides and localization policies are also welcome.

Initiating a new localization team

Basic requirements to initiate a new localization team

  • The Glossary project does not have a localization team for your language yet
  • At least three volunteers
  • At least two approvers
    • two approvers must approve each term
    • unanimous consent must be reached to be approved
    • at least one volunteer must have basic GitHub knowledge and be willing to help the others get up to speed (such as PR, review process, branch, ..)

Instructions to initiate a new localization

1. Join the Slack channel and say hello

If you're interested in creating a new localization team, whether you have a team or are on your own, please join the #glossary-localizations channel on the CNCF slack and say hi. If you have at least three volunteers and are ready to start, request a localization channel for your language (e.g., #glossary-localization-korean). If you are still looking for more volunteers, let everyone in the channel know. There may be someone in there looking for a team as well.

2. Opening an issue to notify initiation of a new localization

Open an issue and select the Initiate a New Localization Team template.

With this issue, new localization teams are requesting:

  • their own development branch (ex: dev-ko branch).
  • permission for approving localized content
    • teams will select the most suitable team members as approvers (no more than 4 per localization team)
    l10n team approvers will have push permission to this repository.
They will manage (merge) PRs for their l10n contributions in their development branch.
However, their ability to merge PRs to the `main` branch is restricted.
Please note: although they can review and approve PRs to the `main` branch, they should not approve PRs that aren't related to their own localization teams.

Localization teams should use their assigned development branch for the following localization tasks (example of a dev branch: https://github.com/cncf/glossary/tree/dev-ko; dev-ko stands for Korean dev branch).

3. Configuring a new language

Open a PR with the localization initiation following this example: #291.

3-1. Adding a new language setting to site configuration

To add a new language to the site, modify config.toml (Note: localization teams should use their assigned development branch for this).

The [languages] block of config.toml is used to set the language. For instance, [languages.en] stands for English and [languages.ko] for Korean language configuration. Go to the [languages] block in config.toml and find a place for your new localization:

  • The English language always stays first.
  • Other languages are sorted based on the alphabetized English translation of their names (see how currently existing localizations are ordered as an example).
  • Each localization is written in its own language followed by the English translation in parentheses — e.g., 한국어 (Korean).
  • The weight parameter in the config is used for sorting (1 is for English, 2 is for the alphabetically first language, 3 is for the second one, and so on).

For instance, you're adding a new block for the Korean localization. You calculated its weight as 8. Find the language block with weight = 7 and add your new block afterwards:

  • Example of New language block for /config.toml 
    [languages]
...
weight = 7

+[languages.ko]
+title = "클라우드 네이티브(Cloud Native) 용어집"
+description = "CNCF 클라우드 네이티브 용어집 프로젝트는 클라우드 네이티브 애플리케이션에 대한 대화를 나눌 때 공통의 용어를 참조하여 사용하도록 하는 목적을 가지고 있다."
+languageName = "한국어 (Korean)"
+contentDir = "content/ko"
+weight = 8

Since the weight values should always be kept consistent, please remember to increment the weights of all the languages following your newly added localization.

3-2. Adding a file for site strings

i18n/<localization>.toml sets up language-specific site strings. For a new localization, add a file i18n/<localization>.toml based on i18n/en.toml. other = "<English site strings>" in i18n/<localization>.toml can be translated.

3-3. Adding a new localization directory

Translated Glossary terms are saved in the appropriate language directory inside /content/.

Create a subdirectory in content and name it using the appropriate two-letter language code (content/<localization>). For example,

contents/en
contents/ko
...

3-4. Minimum required content

Localize content and save to content/<localization>.

Your first PR should include these pages:

  • Home: content/en/_index.md -> content/<localization>/_index.md
  • How to contribute: content/en/contribute/_index.md -> content/<localization>/contribute/_index.md
  • Style guide: content/en/style-guide/_index.md -> content/<localization>/style-guide/_index.md

3-5. Check configuration works and open a PR

Before opening a PR, ensure the website with the updated configuration works by running Hugo server. If it does, select the new language on the local website.

image

Open a PR (ex: #291) and wait for it to be reviewed by the maintainers.

4. Localizing and adding minimum required terms

Before going live with a localized Glossary, you need at least:

  • 10 translated terms

How localization teams achieve that, is up to them. For instance, they can use issues to assign contributors to translation terms and track progress (ex: #269).

5. Merging the localization branch into main branch

After completing the minimum required terms for a new localization, open a PR to merge commits in the localization branch into the main branch. (ex: dev-ko to main).

Once the PR is merged, the localized content will go live on its website 🎉

Join an existing localization team

To join an existing team, hop on the #glossary-localizations and #glossary-localization-[language name] channels on the CNCF Slack. Introduce yourself, let the team know you want to contribute, and the team will take it from there.

If the team seems inactive (no response after several days), reach out to @Seokho Son, @Jihoon Seo, @nate-double-u, or @Noah Ispas on the #glossary-localizations channel.

Localization team guidelines

Every localization team may have its own process of working on localizing terms. However, here are some guidelines that are common for all localization teams:

  1. Only terms with the status Completed in the English version are ready to be localized.
  2. All contributions related to localization have to be based on the dev-xx branch, and PRs need to target dev-xx.
  3. Localization teams need to get changes from the main branch in their dev-xx branch from time to time. Therefore a PR should be opened where the main branch is merged into dev-xx. The glossary maintainers will then choose the rebase method to complete the PR and keep the history linear.
  4. A localized term does not have to match the English version completely. Also, the localized and English versions of terms can coexist independently throughout updates. Localization teams can decide to which degree localized terms have to match their English version and how to handle updates on the English term. To learn how other teams keep up to date with changes in the English version, please refer to this discussion on the topic.