ek9_extract_to_localized_text
Replaces the selected string literal with `<localeAccessor>.<name>(args)` and adds the text method to every locale of the i18n file in one atomic changeset, answering the editor envelope: status (applied | ready | would-fail | conflicts | error), written, edits[], summary and translationDebt[] naming the locales left placeholder-stubbed.
When to use it
'Move this hard-coded user-facing string into the i18n text type' is one call: {file, startLine, startColumn, endLine, endColumn (1-based) over the literal, textTypeName, name, localeAccessor}.
When not to use it
- The string is already in the i18n surface and you want to change a body - use
ek9_edit_localized_text(update-text-method). - Greenfield i18n authoring with no source call-site to rewrite — use
ek9_edit_localized_text(add-text-method / create-text-type). - The selection is a `+`-style concatenation ("a" + var + "b"), not a single literal — run
ek9_rewrite_string_concatfirst to make it a backtick interpolation, THEN re-run this tool on the rewritten range. - The string is not user-facing (debug log, internal diagnostic, assert message) — leave it.
Details
Parameter inference from `${...}`: simple ref → symbol name+type; property access (${p.x}) → receiver name+type; method call (${items.size()}) → return-type heuristic ('count'), receiver-name fallback - a parameters override must match the inferred COUNT and ORDER (types can widen, names can differ). textTypeName discovery is cross-module — resolved through the module's references block, so a centralized text type is found and extended, not duplicated. Conflicts are all mechanical and caller-repairable — notably selection-is-concat-not-literal (run ek9_rewrite_string_concat first), no-text-type-instance-in-scope, and i18n-file-supplied-for-existing-text-type (drop i18nFile — the existing block locations govern); when the type already spans multiple locales an omitted primaryLocale silently defaults to the first locale, so supply it. translationDebt[] lists the non-primary locales stubbed with the primary body plus an //AI: translate directive.
Arguments
| Argument | Type | Required | What it is |
|---|---|---|---|
endColumn | integer | 1-based column of the literal's closing quote or backtick, inclusive. | |
endLine | integer | 1-based line the literal ends on (the same line for a one-line literal). | |
file | string | yes | The .ek9 source file holding the literal - workspace-relative (absolute inside the workspace accepted). |
i18nFile | string | Destination: required when textTypeName does NOT yet exist in the module. Workspace-relative path where the new text type lands. | |
localeAccessor | string | yes | Name of an existing variable in scope at the selection site whose type is the target text type. The rewritten call site becomes `<localeAccessor>.<name>(<args>)`. |
name | string | yes | Name for the new text method. |
parameters | array of any | Optional override of the auto-inferred parameter signature. Supplied parameters must match the inferred count AND order; names can differ; types can widen. | |
primaryLocale | string | Required when textTypeName does NOT yet exist. Strongly recommended whenever the text type already exists in multiple locales. | |
selection | object | IDE alias for the four flat keys: {startLine, startCol, endLine, endCol}, 1-based inclusive. | |
startColumn | integer | 1-based column of the literal's opening quote or backtick, inclusive. | |
startLine | integer | 1-based line the string literal starts on. | |
supportedLocales | array of string | Optional for new text type creation. | |
textTypeName | string | yes | Target text type (PascalCase). If it exists in the module, the method is added via add-text-method semantics internally. If it does not exist, the tool creates it. |
It also takes the arguments every tool takes.
See also
- Show me in the IDE: Chapter 8: a text type, built
- Show me in the IDE: Extract to Localized Text