mkdocs-material/docs/contributing/adding-a-translation.md

Adding a translation

We can't believe it ourselves but with the help of community contribution, Material for MkDocs already supports 50+ languages. As you can imagine, it's impossible for us maintainers to keep all languages up-to-date (we just don't speak 50+ languages). That's why we need the help of our international community to help us add new or update translations, as new feature releases sometimes require new translations.

If you would like to help us to make Material for MkDocs more globally accessible and have noticed a missing translation in your language or want to add a new one. In that case, we have simplified the contributing process for you. Just follow the few steps of the guide below.

Before adding a translation

Given the constant expansion of our project and the frequent translation updates, it is essential to check the following things before submitting a translation contribution.

List of supported languages

Chances are your language is already supported by Material for MkDocs. To check if your language is supported or needs improvements and updates, we would advise you to check the list of supported languages.

:material-earth-plus:  Search for your language{ .md-button .md-button--primary }

In case your language is already supported, you can add missing translations, displayed below each language. If your language is not on the list of supported languages, you can contribute translations by opening a new issue and adding a translation by following the guide below.

Please note, that we use region designators in conjunction with regions, and cluster all languages using language designators with regions. Language region designators consist of codes that represent countries and follow the ISO 3166-1 standard, which employs two-letter capitalized codes. If you need to specify a particular dialect, please utilize this system by hyphenating a language designator with a region designator. For instance, to specify the British English, use the "en" language designator and indicate the locale as "en-GB."

Issue tracker

Our issue tracker might already contain an open issue with a contribution with missing translations for your language that still needs to be integrated by us maintainers. To avoid investing your time in duplicated work, please search the issue tracker beforehand.

:octicons-issue-opened-24:  Search our issue tracker{ .md-button .md-button--primary }

Update supported languages

Have you noticed that other users haven't yet updated your language? You are welcome to contribute and add any missing translations by clicking the link provided underneath each language in the list of supported languages. This link will direct you to a new issue template that is pre-filled with all the necessary information. Any fields that can be adjusted will be highlighted for your convenience.

:material-translate-variant:  Add missing translations{ .md-button .md-button--primary }

---

At this point, when you have made sure that Material for MkDocs doesn't already support your language you can add translations for it by following the issue template.

Issue template

We have created a new issue template to make contributing translations for new languages as simple as possible. It is the result of our experience with 50+ language contributions and updates over the last couple of years. We recently simplified the language contribution process, and the new template consists of the following parts:

• Title

• Translations

• Country flag optional

• Checklist

Title

Translation issue titles are simple. When adding a new language, the first part of the title with "Add translations for..." is already pre-filled in the template, and you need to replace the three dots with your language name. If adding missing translations for a language from the list of supported languages, the title is already set with no need for adjustment.

	Example
:material-check:{ style="color: #4DB6AC" } Clear	Add translations for German
:material-close:{ style="color: #EF5350" } Unclear	Add translations ...
:material-close:{ style="color: #EF5350" } Generic	German

Translations

With the preliminary work done, you can now add all missing translations for your language. Each label on the right side containing the ⬅️ icon is missing a translation. To ensure the accuracy of your translation, consider double-checking the context of the words by looking at the English version.

After adding the translation, remove the ⬅️ icon from each translated line. If you don't know how to translate specific fields, simply leave them for other contributors to complete.

Translation context

TO DO MARTIN - explain the translation context . .

Country flag

Congratulations on contributing translations for a new language! To make it easier for you and others to find the language in our list of supported languages, please select the best-fitting flag for your language from our documentation's Icons, Emojis site by entering the command flag in the search field.

!!! warning "Icon limitation by Twemoji"

Please note that only icons provided by Twemoji can be used. If your flag is 
not available on the list on the [Icons, Emojis site], please choose an 
alternative.

Why this might be helpful: adding a country flag next to the country name can be helpful for you and for others to find the language in the list of supported languages faster and easier. If your country's flag is not supported by Temoji, it is best that you provide us with an alternative instead of us choosing one for you.

Checklist

Thanks for following the guide and creating a high-quality and complete translation issue – you are almost done. The checklist ensures that you have read this guide and have worked to your best knowledge to provide us with everything we need to know to integrate your contribution to Material for MkDocs.

We'll take it from here.

---

Authors credits

Authors who submit a translation using the template above will be credited as co-authors in commits for Material for MkDocs. To list your account as a co-author without knowing or revealing your email address, we will use your GitHub-provided no-reply email, following GitHub's recommended workaround to protect your privacy. This way, your commit will count as a contribution without opening a pull request.

Contributing via pull request

If you want to contribute missing translations by creating a pull request to be listed as the sole author of the commit, you can open a PR after submitting the translation issue. Ensure you thoroughly read the pull request guide below to prevent breaking functionality in the translation file.

1. Fill out a translation issue according to the guide and submit it in the issue tracker.

2. Tick the box for the last point in the "Before submitting..." section.

   • Optional: I want to integrate this translation myself and create a pull request following the contribution guide.

3. Fork the Material for MkDocs repository, set up a development environment and create a separate git branch on which you make all your changes.

4. Please review all existing language files in the repository and search for your language. If a file for your language already exists, please use it for your edits or create a new file if your language is not listed by copying one of the existing files.

5. Add the missing translations for your language to the best of your knowledge and save the changes.

   !!! warning "Important" Only add the translations that are different from the defaults. For example, if your language is left-to-right, don't add the direction translation, as English is also left-to-right. The following translations are for technical purposes, and should not be updated. If they're missing from your language, it's for a good reason:

   - `search.config.lang`
   - `search.config.pipeline`
   - `search.config.separator`
   

6. Open the English translations file and compare your translations with the up-to-date English translations file.

7. Before submitting a pull request, build the theme. This is a mandatory requirement for your PR to get accepted, as the theme should be installable through GitHub at all times.

8. After building the theme, commit the compiled output, push your branch to GitHub and send a PR to mkdocs-material:master. If we suggest changes, make the required updates, rebase your branch, and push the changes to your GitHub repository, which will automatically update your PR.

9. After your PR is merged, you can safely delete your branch and pull the changes from the main (upstream) repository.

After your PR was merged by us maintainers, you can start using the new language.