translations/create-translation-file starts a translation for a bundle in a locale it does not yet have, seeded from the POT template so every translatable string is there and empty, ready to fill in.
It takes no path. Where a translation belongs depends on the text domain and whether the bundle is a theme, and Loco already knows the answer — supplying a path would only be a way to get it wrong.
At a glance
| Ability | translations/create-translation-file |
| Toolset | Loco Translate — toolset/loco-translate |
| Group | Loco Translate › Translation Files |
| Requires | Loco Translate, active on the site |
| Capability | manage_options |
| Safety | Writes data |
| Repeatable | Not idempotent — each call changes the row set, so re-running is not a no-op |
| Ships in | AcrossAI Abilities Manager 0.0.34 and later |
How it works
It refuses rather than overwrites. If a translation for that locale already exists, this stops — because the alternative is silently discarding somebody’s work.
Seeding comes from the POT. A bundle with no template produces a thin or empty file, which is why translations/get-bundle is worth calling first and translations/extract-strings worth running when there is no template at all.
The compiled artefacts are written immediately, so the new locale is live — showing untranslated source text, which is correct — rather than half-created.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
bundle | string | Yes | Bundle id, handle or slug — all three appear in Loco’s own screens. Use core for WordPress itself. |
domain | string | No | Text domain. Omit for the bundle default. |
locale | string | Yes | Locale to create, such as de_DE. Call translations/list-locales for valid tags. |
What comes back
| Name | Type | What it is |
|---|---|---|
artefacts | object | Bytes written per artefact — po_bytes, mo_bytes, php_bytes, json_files, json_bytes. Read back from disk rather than reported by Loco, so a zero mo_bytes means the site is still serving the old strings. |
file | string | The PO file that was created. |
string_count | integer | How many strings it was seeded with. |
success | boolean | Whether the call completed. |
message | string | A one-line summary of what happened, suitable for showing a human. |
error_code | string | Present only on failure — a stable machine-readable reason, such as a missing field, a wrong field type or an unmet confirmation. |
Example
Ask your assistant:
Start a Spanish translation for this theme.
It resolves to one call:
{
"ability": "translations/create-translation-file",
"parameters": {
"bundle": "twentytwentyfive",
"locale": "es_ES"
}
}Worth knowing
- Refuses if the locale already exists. That is a guard, not a failure.
- A low
string_countusually means the bundle has no POT template to seed from. - Get valid locale tags from
translations/list-localesrather than guessing.
Related abilities
- List Locales — pick a valid tag
- Update Translation Strings — fill the new file in
- Extract Strings To Template — when there is no POT to seed from
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category