Translations Editor

List Languages

{"data": {"default": "en", "languages": [{"code": "de", "has_overrides": false}, {"code": "en", "has_overrides": true}, {"code": "fr", "has_overrides": false}]}}

List Sources

{"data": {"lang": "en", "providers": [{"id": "theme:quark", "kind": "theme", "slug": "quark", "label": "Quark", "enabled": true, "key_count": 42, "namespaces": [{"name": "THEME_QUARK", "key_count": 42}]}]}}

A source id is system:core, plugin:<slug>, theme:<slug> or user:overrides, and kind is system, plugin, theme or user. enabled says whether a plugin is enabled or a theme is the active one; it is always true for core and the site's overrides. Pass an id as provider to List Keys to see that source's strings.

Get Coverage

{"data": {"source_lang": "en", "coverage": [{"code": "fr", "total": 1868, "translated": 1702, "missing": 166, "overridden": 3}]}}

total is the number of keys in the source language, and translated and missing are counted against that key set only, so a stale key that only an old translation still carries doesn't count. overridden is the number of site overrides in the language, for any key.

List Keys

{"data": [{"key": "THEME_QUARK.SEARCH", "namespace": "THEME_QUARK", "source_value": "Search", "providers": ["theme:quark"], "owner": "theme:quark", "known": true, "values": {"en": {"value": "Search", "state": "shipped", "shipped": "Search"}, "fr": {"value": "Rechercher", "state": "overridden", "shipped": "Recherche"}}}], "meta": {"pagination": {"page": 1, "per_page": 20, "total": 1, "total_pages": 1}}, "links": {"self": "/api/v1/i18n/keys?page=1&per_page=20"}}

q matches the value as well as the key because people know the words on screen, not the key behind them. source_value is the site's override in the source language when one exists, otherwise the shipped value. providers lists every source that ships the key and owner is the one whose value wins at runtime. See the collection introduction for the cell states.

The pagination links keep every query parameter you sent (search, filters, languages), so following one stays within the same filtered view.

Get Key

{"data": {"key": "THEME_QUARK.SEARCH", "namespace": "THEME_QUARK", "source_value": "Search", "providers": ["theme:quark"], "owner": "theme:quark", "known": true, "values": {"de": {"value": "Suche", "state": "shipped", "shipped": "Suche"}, "en": {"value": "Search", "state": "shipped", "shipped": "Search"}, "fr": {"value": "Rechercher", "state": "overridden", "shipped": "Recherche"}}}}

Get Overrides

{"data": {"lang": "fr", "scoped": true, "namespace": "THEME_QUARK", "count": 1, "yaml": "THEME_QUARK:\n  SEARCH: Rechercher\n"}}

scoped is true when namespace was given, and count is the number of overrides included. Save the edited text back with Replace Overrides, passing the same namespace.

Update Overrides

{"set": {"THEME_QUARK.SEARCH": "Rechercher"}, "unset": ["PLUGIN_ADMIN.TITLE"]}

{"data": {"written": {"THEME_QUARK.SEARCH": "Rechercher"}, "removed": ["PLUGIN_ADMIN.TITLE"], "reverted": [], "unknown": [], "rows": [{"key": "THEME_QUARK.SEARCH", "namespace": "THEME_QUARK", "source_value": "Search", "providers": ["theme:quark"], "owner": "theme:quark", "known": true, "values": {"fr": {"value": "Rechercher", "state": "overridden", "shipped": "Recherche"}}}, {"key": "PLUGIN_ADMIN.TITLE", "namespace": "PLUGIN_ADMIN", "source_value": "Title", "providers": ["plugin:admin"], "owner": "plugin:admin", "known": true, "values": {"fr": {"value": "Titre", "state": "shipped", "shipped": "Titre"}}}]}}

A set whose value equals what the source ships is stored as a removal rather than an override, so the file only holds real differences and keeps following the source's future wording. Those keys are listed in reverted. Keys no source ships are still written, and listed in unknown.

written holds the keys stored as overrides with their values, and removed the keys whose existing override was deleted. rows has a fresh matrix row for every key the request touched, with a cell for this language only, so the editor can update in place.

Replace Overrides

{"yaml": "THEME_QUARK:\n  SEARCH: Rechercher\n", "namespace": "THEME_QUARK"}

{"data": {"count": 1, "dropped": [], "unknown": [], "removed": 0}}

With namespace, only the overrides under that prefix are replaced and everything else in the file is kept. That is what makes saving a filtered view safe: an unscoped save of one theme's strings would delete every other override. A key outside the namespace fails the whole save with a 422 that names the out-of-scope keys (up to five), rather than a parse error.

Values equal to the shipped value are not stored and are listed in dropped. Keys no source ships are saved and listed in unknown rather than rejected, so a typo is reported instead of doing nothing. count is the number of overrides stored from this YAML, and removed how many fewer in-scope overrides exist than before.

Translate Status

{"data": {"available": false, "installed": true, "enabled": true, "reason": "not_configured", "max_keys": 200}}

reason is null when available is true, otherwise not_installed, not_enabled or not_configured (the plugin has no configured provider), so a client can tell the site owner what to do. max_keys is the most keys one Translate Keys request accepts.

Translate Keys

{"source_lang": "en", "target_lang": "fr", "keys": ["THEME_QUARK.SEARCH", "PLUGIN_ADMIN.TITLE"]}

{"data": {"source_lang": "en", "target_lang": "fr", "proposals": [{"key": "THEME_QUARK.SEARCH", "source": "Search", "value": "Rechercher", "ok": true, "reason": null}, {"key": "PLUGIN_ADMIN.TITLE", "source": "Title", "value": "Titre", "ok": true, "reason": null}]}}

Placeholders are masked before the text is sent and checked when it comes back. Proposals come back in the order the keys were sent. A proposal with ok: false has a null value and one of these reason values:

The first three are decided before the provider is called, so they cost nothing.

Import Status

{"data": {"present": true, "plugin_enabled": true, "config_path": "/var/www/grav/user/config/plugins/translation-strings.yaml", "pending": 4, "total": 6, "languages": [{"code": "fr", "total": 6, "new": 3, "already": 1, "conflict": 1, "shipped": 1, "unknown": 0, "keys": [{"key": "THEME_QUARK.SEARCH", "status": "new", "unknown": false, "current": null, "value": "Rechercher"}]}]}}

present is true when the plugin has at least one override configured, and plugin_enabled matters because while the plugin is enabled its values still win over user/languages. pending counts the keys an import would write (new plus conflict). config_path is the absolute path of the plugin's config file; demo accounts get (hidden in demo mode) instead.

Per language, new keys have no override yet, already keys are overridden with the same value, conflict keys are overridden with a different value that importing replaces with the plugin's, and shipped keys equal the shipped value so importing stores nothing. The counts are exact, but keys lists at most 50 keys per language. In each listed key, current is the site's existing override (or null) and value is the plugin's value.