ek9_edit_localized_text

Rewrites the `defines text for "<locale>"` blocks of one text type in every locale that defines it (one atomic edit, so E07150 locale-completeness holds) and answers the editor envelope: status (applied | ready | would-fail | conflicts | error), written, edits[], summary, and translationDebt[] naming each {textType, locale, method} left placeholder-stubbed.

Category: Editor · Compare: NEW IDE surface — JavaFX dialog for create-text-type, right-click context menu inside `defines text for` blocks

When to use it

'Add / change / remove a translatable text method or locale' is one call: pick mode (create-text-type, add-text-method, add-locale, update-text-method, remove-text-method, remove-locale) and name the textTypeName.

When not to use it

• Promoting a hard-coded string literal in EK9 source into a text method - use ek9_extract_to_localized_text (it rewrites the call site too).
• Authoring a `defines class`/`record`/etc. - text is a distinct construct kind; use ek9_new_construct instead.
• A regular method on a class/trait/component — text methods are localized-string bodies, structurally different; use ek9_add_method instead.
• Changing an existing translated method's SIGNATURE — update-text-method rejects it (signature-change-not-allowed); do remove-text-method + add-text-method instead (ek9_change_signature cascades over type hierarchies, not locale groups).
• Non-uniform locale coverage (one locale needs different params) — EK9 rejects this via E07150; author two separate text types by hand instead.

Details

Enforcement of per-text-type locale completeness is the distinguishing trait: adding a method to one locale without the others fires E07150, so create / add-text-method / add-locale / remove-text-method succeed across every locale defining the text type or block entirely; update-text-method is the only per-locale-subset mode (signature immutable); remove-locale is module-wide, blocking on literal-locale constructor calls and on would-orphan-text-type (escalation — last defining locale). Text methods can overload - when methodName matches >1 overload you MUST supply parameters or it blocks with method-ambiguous-supply-params (candidateOverloads[] lists signatures); locale identifiers must match [a-z]+(_[A-Z]+)?. Auto-stubbed bodies emit a two-line placeholder (`//AI: translate the message` + empty `""`) surfaced in translationDebt[], and update-text-method rewrites the whole method block, discarding in-body comments.

Arguments

It also takes the arguments every tool takes.

Recorded calls

Real calls, recorded against small projects and checked on every build - a changed answer fails it. 3 of the 17 recorded are shown.

Conflict unknown reference locale

Request

{
  "mode" : "add-locale",
  "newLocale" : "fr",
  "referenceLocale" : "es_ES",
  "targetFile" : "text.ek9"
}

Response

{
  "conflicts" : [ {
    "kind" : "reference-missing",
    "reason" : "reference-locale-missing",
    "suggestedRepair" : "Pick a referenceLocale that already contains the text types you want to clone"
  } ],
  "edits" : [ ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "risk" : {
    "crossesModuleBoundary" : false,
    "estimatedSeverity" : "trivial",
    "fileCount" : 0,
    "lineCount" : 0,
    "touchesPublicApi" : false,
    "touchesTests" : false
  },
  "status" : "conflicts",
  "summary" : "Reference locale 'es_ES' contains no text types",
  "workspaceHash" : "<workspace-hash>",
  "wouldBeDiagnostics" : [ ],
  "written" : false
}

Dirty overlay honoured

Request

{
  "dirtyOverlay" : {
    "<workspace-root>/text.ek9" : "#!ek9\ndefines module com.example.i18n\n\n  defines text for \"en_GB\"\n    WelcomePageText\n      mainWelcome()\n        \"Hello World\"\n\n  defines text for \"de\"\n    WelcomePageText\n      mainWelcome()\n        \"Hallo Welt\"\n\n//EOF\n"
  },
  "dryRun" : true,
  "methodBodies" : {
    "de" : "\"Hallo, neue Welt\""
  },
  "methodName" : "mainWelcome",
  "mode" : "update-text-method",
  "targetFile" : "text.ek9",
  "textTypeName" : "WelcomePageText"
}

Response

{
  "conflicts" : [ {
    "kind" : "locale-mismatch",
    "reason" : "locale-not-defined-for-text-type",
    "suggestedRepair" : "Remove 'de' from methodBodies, or use add-locale to bring the text type into that locale first"
  } ],
  "edits" : [ ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "risk" : {
    "crossesModuleBoundary" : false,
    "estimatedSeverity" : "trivial",
    "fileCount" : 0,
    "lineCount" : 0,
    "touchesPublicApi" : false,
    "touchesTests" : false
  },
  "status" : "conflicts",
  "summary" : "Locale 'de' does not define text type 'WelcomePageText'",
  "workspaceHash" : "<workspace-hash>",
  "wouldBeDiagnostics" : [ ],
  "written" : false
}

Update text method dry run

Request

{
  "dryRun" : true,
  "methodBodies" : {
    "de" : "\"Hallo, neue Welt\""
  },
  "methodName" : "mainWelcome",
  "mode" : "update-text-method",
  "targetFile" : "text.ek9",
  "textTypeName" : "WelcomePageText"
}

Response

{
  "conflicts" : [ ],
  "edits" : [ {
    "endLine" : 12,
    "file" : "text.ek9",
    "startLine" : 12,
    "type" : "delete"
  }, {
    "after" : "\n      mainWelcome()\n        \"Hallo, neue Welt\"",
    "endLine" : 11,
    "file" : "text.ek9",
    "startLine" : 11,
    "type" : "replace"
  } ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "risk" : {
    "crossesModuleBoundary" : false,
    "estimatedSeverity" : "trivial",
    "fileCount" : 1,
    "lineCount" : 2,
    "touchesPublicApi" : false,
    "touchesTests" : false
...

Cut short here: 7 more lines. The whole recorded call.

See also

• Show me in the IDE: Chapter 8: a text type, built