Skip to content

Backend internationalization (i18n)

Backend internationalization covers a few translated database fields. All interface text is translated in the frontend: to fix or add a translation of anything shown in the UI, see the HomePort i18n guide.

Waldur's own backend messages (API errors, notifications) are not translated and are returned in English. Messages that come from Django and Django REST framework themselves, such as This field is required., use the translations bundled with those libraries and follow the request language.

Translated fields

These fields are stored once per language with django-modeltranslation:

Model Fields Registered in
Role description waldur_core/permissions/translation.py
Category title, description waldur_mastermind/marketplace/translation.py
CategoryGroup title, description waldur_mastermind/marketplace/translation.py

The translation.py files are the source of truth if this table falls behind.

Each translated field gets one database column per language in LANGUAGES: description_en, description_et and so on. Reading description returns the column for the language of the current request, which LocaleMiddleware takes from the Accept-Language header. An empty column falls back to English.

Translations are entered by staff:

  • Role descriptions — in the role description dialog of the roles administration, or through the update_descriptions action of the roles API, which accepts one description_<lang> field per language.
  • Categories and category groups — in the Django admin, which shows one input per language.

Making another field translatable

  1. Register the field in the app's translation.py:

    1
2
    class CategoryTranslationOptions(TranslationOptions):
    fields = ("title", "description")

  2. Run makemigrations for the app. The migration adds one column per language.

  3. To accept the per-language values through the API, use TranslatedModelSerializerMixin from waldur_core.core.serializers. It adds a <field>_<lang> serializer field for each language.

Adding a language

  1. Add the language to LANGUAGES in waldur_core/server/base_settings.py.
  2. Add its code to LANGUAGE_CHOICES in waldur_core/server/constance_settings.py, the default list of languages users can choose from.
  3. Run makemigrations for permissions and marketplace. The migrations add the new language's column to every translated field.
  4. In HomePort, add locales/<code>.json, and map the language code to the country whose flag the language selector shows in LanguageCountry (src/navigation/header/LanguageSelectorDropdown.tsx).

Do not use modeltranslation's sync_translation_fields command: it adds the columns directly to the database, outside the migration history.