It's unbelievable – with the help of international community contributions, Material for MkDocs has been translated into 60+ languages. As you can imagine, it's impossible for us maintainers to keep all languages up-to-date, and new features sometimes require new translations.
If you would like to help us to make Material for MkDocs even more globally accessible and have noticed a missing translation in your language, or would like to add a new language, you can help us by following the steps of the guide below.
Before creating an issue¶
Translations change frequently, which is why we want to make sure that you don't invest your time in duplicating work. Before adding translations, please check the following things:
Check language availability¶
With more than 60 languages, the chances are good that your language is already supported by Material for MkDocs. You can check if your language is available, or needs improvements or additional translations by inspecting the list of supported languages:
Your language is already supported – in this case, you can check if there are translations missing, and click the link underneath your language to add them, which takes 5 minutes.
Your language is missing – in that case, you can help us add support for your language to Material for MkDocs! Read on, to learn how to do this.
Search our issue tracker¶
Another user might have already created an issue supplying the 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.
At this point, when you have made sure that Material for MkDocs doesn't already support your language, you can add new translations for it by following the issue template.
We have created an issue template that makes contributing translations as simple as possible. It is the result of our experience with 60+ language contributions and updates over the last couple of years, and consists of the following parts:
When you update an already existing language, you can just leave the title as it is. Adding support for a new language, replace the
... in the pre-filled title with the name of your language.
|Clear||Add translations for German|
|Unclear||Add translations ...|
If a translation contains an icon on the right side, it is missing. You can translate this line and remove the icon. If you don't know how to translate specific lines, simply leave them for other contributors to complete. To ensure the accuracy of your translation, consider double-checking the context of the words by looking at our English translations.
Country flag optional¶
For a better overview, our list of supported languages includes country flags next to the language names. You can help us select a flag for your language by adding the shortcode for the country flag to this field. Go to our emoji search and enter
flag to find all available shortcodes.
What if my flag is not available?
Twemoji provides flag emojis for 260 countries – subdivisions of countries, such as states, provinces, or regions, are not supported. If you're adding translations for a subdivision, please choose the most appropriate available flag.
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 Twemoji, you can help us choose an alternative.
Thanks for following the guide and helping us to add new translations to Material for MkDocs – 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 integrate your contribution.
We'll take it from here.
If you submit a translation using the template above, you will be credited as a co-author in the commit, so you don't need to open a pull request. You have done a significant contribution to the project, making Material for MkDocs accessible to more people around the world. Thank you!