<!-- skill-index: generated by scripts/skill-index.py; make check-skill-index -->

Find it fast

sed -n '<from>,<to>p' SKILL.md one section rather than reading the file; ./mxcli syntax <topic> answers how do I write this for a fraction of either.

lines	section
27-42	The loop
43-74	Statements
75-94	The trap: a language that is not enabled
95-113	Drift: a source string that was edited
114-131	Notes
132-147	Common tasks

<!-- /skill-index -->

Translations

Every user-visible string of a Mendix app — page titles, widget captions, button labels, validation messages, enum captions, menu items — is a Texts$Text with one translation per language. MDL treats them in bulk: one file per language.

The loop

# 1. export: an untranslated string comes back with an EMPTY target
mxcli -p app.mpr -c "describe translations for de_DE" > de_DE.mdl

# 2. fill in the right-hand sides (by hand, or hand the file to an LLM)

# 3. write them back
mxcli exec de_DE.mdl -p app.mpr

That is the whole design: DESCRIBE emits the CREATE form, so the export format and the import format are the same file, and the empty targets are the prompt.

Statements

describe translations [in <Module> | without marketplace] for <lang>;

create translations            [in <Module> | without marketplace] for <lang> ( 'src' as 'target', ... );
create or modify translations  [in <Module> | without marketplace] for <lang> ( 'src' as 'target', ... );
create or replace translations [in <Module> | without marketplace] for <lang> ( 'src' as 'target', ... );

Entries use as, not a colon: a translation maps a user-provided name to another name.

verb	meaning
create	the "add a language" form — refuses if that language already has translations anywhere in scope
create or modify	merge; a source string the file does not name keeps whatever it has
create or replace	the file is authoritative — a translation whose source the file does not name is removed, and the run names what it deleted

IN <Module> scopes both directions, and under OR REPLACE it bounds the deletion — without it, a set of per-module files would wipe each other on every run.

Translating the app, not its Marketplace modules: add without marketplace. Without in, a run reaches the whole project — Marketplace modules, and the Atlas page templates and building blocks in them, included. A module update replaces a Marketplace module's contents, so translations written there are lost at the next update and show up as unexpected diffs until then. The unscoped run warns with a per-module count; without marketplace keeps the run in the app's own modules and names the file's entries it left alone. Use it on describe as well, so the file it emits carries the clause.

The trap: a language that is not enabled

A translation for a language the project has not enabled is stored, passes mx check, and is discarded at build time. Measured with mxbuild --target=deploy: the string reaches nothing under deployment/ — no translations_<code>.properties is produced at all — while the model and Studio Pro both keep it happily.

So translating 400 strings into German can produce exactly no German in the app. create translations warns when the language is not enabled; enable it in project settings first (see the project-settings skill), then re-run.

A stock app makes this easy to hit by accident: it enables one language while its marketplace modules ship translations in nine, so "other languages already have translations here" is true and misleading.

list languages lists languages that have translations, not the enabled ones — a stock app reports 8 while 1 is enabled. describe settings has the enabled list.

Drift: a source string that was edited

The dictionary is keyed on the source string, so Save is translated once for all the places it occurs. The flip side: editing a source string after the file was written stops it matching, which would leave the translation attached to a string that no longer exists.

A key that matches nothing is reported, not skipped — and where the translation identifies the moved source unambiguously, the run names the fix:

Warning: 1 source string(s) in the file matched nothing in the project.

  "Thingz" as "Grejer"
      No text has "Thingz" as its source. A text now reads "Things" and carries
      the sv_SE "Grejer" — the source was probably edited. Change the file to:
        "Things" as "Grejer"

Notes

• Scale. A whole app is a few hundred distinct source strings (411 on a real project measured), so one file per language is comfortably practical.
• A rewrite does not lose other languages. Re-executing a page or microflow keeps the translations MDL cannot express; you do not have to re-import a language after editing a document.
• The source language is the project's default: the left-hand column is what DESCRIBE shows for that language, so change DefaultLanguageCode before exporting if you want a different source. It is also the language a new caption is written in — Caption: 'Opslaan' is stored under the default, so set it before authoring pages, not after. Changing it later does not move text that already exists, and nothing warns: mx check is 0 errors either way (mendixlabs/mxcli#970). Re-running the create statements fixes it. See project-settings.
• Translating into the source language is refused — it would overwrite the strings everything else is keyed on.

Common tasks

mdl 1;
-- what is still untranslated, and how much
describe translations for de_DE;        -- ends with "N source string(s), M translated, K to go."

-- one module at a time
describe translations in Sales for de_DE;

-- make a file authoritative for one module only
create or replace translations in Sales for de_DE ( 'Order' as 'Bestellung' );

-- remove a language's translations entirely
create or replace translations for de_DE ( );