Internationalization (i18n)
Locales
Karrot is available in different languages. So, instead of adding English text directly to a component's source file, we add a key instead. This key points to a text in each of the locale files.
All locale files can be found under src/locales/
. For example the Spanish locale file is located at src/locales/locale-es.json
.
Instead of
<ChangePhoto
...
:label="Group logo"
:hint="Click to upload your group logo!"
...
/>
we write
<ChangePhoto ... :label="$t('GROUP.LOGO')" :hint="$t('GROUP.SET_LOGO')" ... />
$t(...)
is a function provided by vue-i18n which does all the lookup magic.
Adding new text to locales
- Add a new key-value pair to
src/locales/locale-en.json
- As a convention keys are CAPITALIZED.
- Keys can be nested for better structure.
- Do not add the key to the other locale-*.json files. They will be added automatically by the CI tool after merge to master and translated by transifex.
Adding new locales
Hey stranger
Do you know how to add new locales? Improve this documentation by answering this question.
Codeberg workflow
Once a week a CI job will run to update the locales, here's how it works.
CI technical detail
During CI we have a custom Woodpecker CI plugin to update the locales: karrot/plugin-update-locales. The CI configuration is in .woodpecker/update-locales.yml (frontend) and .woodpecker/update-locales.yml (backend).
It runs according to the schedule configured (frontend, backend). currently, once a week. You could also run it manually if you wanted (frontend, backend - select the ci/update-locales
branch).
1. Setup branch
It takes the repository main
branch (the working branch), and creates ci/update-locales
branch (or deletes and recreates it from main
if it already exists).
This branch is always managed by the CI job, and not something you manage separately. Occasionally it might be useful to switch to it locally to review translations on your own machine.
2. Push source files
The source translations files are pushed to transifex. The source files are the English text. This is what the rest of the translation files are there to translate.
For newly added or changed translation entries, transifex can then do whatever it does to show translators that there are texts to translate.
3. Pull translated files
Then we pull the latest updated translation files. These are the files that have been translated from the source files by the nice translators.
If they have not been translated the translation files contain the content from the source files. E.g. if a text has not been translated into German, the German file will contain the English text.
4. Push back to Codeberg
Now with all the changes made, the files are commited on the ci/update-locales
branch and pushed back to Codeberg. A PR is created if it doesn't already exist.
Check karrot-frontend/pulls or karrot-backend/pulls to find it the latest open one (if available).
5. Your job: merging it!
It does not get automatically merged into main
, that's your job!
It might be useful to check the "Files changed" tab on the PR to have a look at what's been updated.
You'll might notice English text in translated files, this is normal and just means some text is new or updated and hasn't been translated yet.
If you're happy with how it looks and you have appropriate permissions, you can merge it! Press the "Create squash commit" button 🚀
It will then be merged into main
, and a CI job will kick off to deploy that to dev.karrot.world from where you can view it.