mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
237 lines
11 KiB
Markdown
237 lines
11 KiB
Markdown
|
# 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][Search for your language]{ .md-button .md-button--primary }
|
|||
|
|
|
|||
|
|
[list of supported languages]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language
|
|||
|
|
[Search for your language]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language
|
|||
|
|
|
|||
|
|
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."
|
|||
|
|
|
|||
|
|
[Adding a translation]: https://github.com/squidfunk/mkdocs-material/issues/new?assignees=&labels=change+request&template=04-add-a-translation.yml&title=Add+translations+for+...
|
|||
|
|
[ISO 3166-1 standard]: https://lingohub.com/developers/supported-locales/language-designators-with-regions
|
|||
|
|
|
|||
|
|
### 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][Search our issue tracker]{ .md-button .md-button--primary }
|
|||
|
|
|
|||
|
|
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
|
|||
|
|
[search our issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
|
|||
|
|
|
|||
|
|
### 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][Update your translations]{ .md-button .md-button--primary }
|
|||
|
|
|
|||
|
|
[List of supported languages]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language
|
|||
|
|
[Update your translations]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
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] <small>optional</small>
|
|||
|
|
- [Checklist]
|
|||
|
|
|
|||
|
|
[Title]: #title
|
|||
|
|
[Translations]: #translations
|
|||
|
|
[Country flag]: #country-flag
|
|||
|
|
[Checklist]: #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
|
|||
|
|
|
|||
|
|
[List of supported languages]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language
|
|||
|
|
|
|||
|
|
### 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.
|
|||
|
|
|
|||
|
|
[English version]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
|
|||
|
|
|
|||
|
|
#### 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.
|
|||
|
|
|
|||
|
|
[Icons, Emojis site]: https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search
|
|||
|
|
|
|||
|
|
### 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.
|
|||
|
|
|
|||
|
|
[GitHub's recommended workaround]: https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors
|
|||
|
|
|
|||
|
|
## 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.
|
|||
|
|
- [x] __Optional__: I want to integrate this translation myself and create a
|
|||
|
|
pull request following the [contribution guide](https://github.com/squidfunk/mkdocs-material/blob/master/CONTRIBUTING.md).
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
[translation issue]: https://github.com/squidfunk/mkdocs-material/issues/new?assignees=&labels=change+request&template=04-add-a-translation.yml&title=Add+translations+for+...
|
|||
|
|
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues/new/choose
|
|||
|
|
[existing language files]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages
|
|||
|
|
[English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
|
|||
|
|
[development environment]: https://squidfunk.github.io/mkdocs-material/customization/#environment-setup
|
|||
|
|
|
|||
|
|
__After your PR was merged by us maintainers, you can start using the new language.__
|