extract-text
Extracts hard-coded user-facing strings from TypeScript or JavaScript source and externalizes them into locale files as YAML, JSON, or MsgResource (`.msg.js` via `@worldware/msg` / `@worldware/msg-cli
SKILL.md.agents/skills/extract-text/SKILL.md
GitHubExtract Text
Externalize hard-coded UI copy from TS/JS into locale entries and wire the source to look up those keys.
Instructions
- Identify the target file(s) and the project's locale layout (path, format, key style, i18n API).
- Choose the output format (YAML, JSON, or MsgResource) using Format selection.
- If the project already has a convention for keys and lookups, match it. Otherwise use the defaults below.
- Extract only user-facing strings. Leave code identifiers, URLs, CSS classes, log messages, test fixtures, and non-copy constants alone unless the user asks otherwise.
- Propose keys, show a before/after for the source file, and the locale entries — then apply the edits.
Format selection
Resolve the target format before writing files:
- User said a format → use it (YAML, JSON, or MsgResource).
- Infer from the project (strongest signal wins):
@worldware/msg,msg-cli,i18n/resources, or*.msg.js/*.msg.ts→ MsgResource- Locale / translation
*.json(and no MsgResource layout) → JSON - Locale
*.yml/*.yaml→ YAML
- Unclear or conflicting signals → ask the user which they prefer: YAML, JSON, or MsgResource. Do not guess.
When the format is MsgResource, follow MsgResource scaffolding before adding strings. Do not hand-write new project or resource files — use @worldware/msg-cli.
Defaults (when no project convention exists)
| Concern | Default |
|---|---|
| Format | Ask the user if none can be inferred |
| YAML path | locales/en.yml |
| JSON path | locales/en.json |
| MsgResource path | Created by msg create resource under directories.i18n (often src/i18n/resources/<title>.msg.js) |
| Key shape | Nested dotted keys for YAML/JSON: feature.section.name. Flat string keys for MsgResource .add('feature.section.name', ...) |
| Lookup | Prefer the project's i18n helper (t, i18n.t, useTranslation, resource.get, MsgMessage, etc.). If none, use t('key') and note that the caller must provide t. |
| Value | Exact original string (preserve punctuation and placeholders) |
Workflow
Copy and track:
Extract progress:
- [ ] 1. Choose output format (infer or ask)
- [ ] 2. If MsgResource: scaffold via msg-cli (init → project → resource)
- [ ] 3. Locate hard-coded strings
- [ ] 4. Choose keys
- [ ] 5. Add locale entries (YAML / JSON / MsgResource)
- [ ] 6. Replace literals with lookups
- [ ] 7. Verify imports / types still work
MsgResource scaffolding
Use @worldware/msg-cli (npx msg … or a local/global msg). Do not invent project/resource files by hand. Details and flags: references/FORMATS.md.
Run these checks in order; stop and ask whenever required input is missing.
- Init — If
package.jsonlacksdirectories.i18n/directories.l10n(or the i18n/l10n layout is missing), tell the usermsg inithas not been run and ask permission to run it. Offer defaults (src/i18n,res/l10n) or custom--i18nDir/--l10nDir. On approval:npx msg init(add path flags if they chose custom dirs). Do not proceed until init succeeds. - Project — List existing files under the i18n
projectsdirectory.- None → Prompt to create one. Ask for:
projectName, source locale, one or more target locales, and optionally--format(MF1|MF2|NONE, defaultMF2). On approval:npx msg create project <projectName> <source> <targets...> [-f <format>]. - Some exist → Still ask which project to use (list names). Do not assume.
- None → Prompt to create one. Ask for:
- Resource — Ask for the resource title (file stem, e.g.
Messages→Messages.msg.js). Then create it:npx msg create resource <projectName> <title>.- If the file already exists, ask whether to reuse it (append
.addonly) or recreate with--force(destructive). Default to reuse when the user is extracting into that resource.
- If the file already exists, ask whether to reuse it (append
- Extract — Replace sample
.add(...)stubs from the CLI with real keys/values (or append after them), then wire source lookups.
Never run msg init, create project, or create resource with guessed names/locales — always confirm with the user first.
1. Locate hard-coded strings
Scan JSX/TSX text nodes, string props (title, label, placeholder, aria-label, alt, button/link children), and user-visible template literals.
Skip: import paths, data-testid, enum/const names used only in logic, GraphQL/SQL, and developer-only error strings.
2. Choose keys
- Scope by feature or screen:
settings.profile.save, notsave. - Reuse an existing key when the copy and meaning match.
- Keep keys stable and descriptive; do not encode the full English sentence in the key.
- For interpolations, keep placeholders consistent with the project (
{{name}},{name},{$name}, or%{name}).
3. Add locale entries
Merge without clobbering unrelated keys. Use the format-specific shapes in references/FORMATS.md.
YAML
settings:
profile:
save: Save changes
greeting: Hello, {{name}}
JSON (nested key-value)
{
"settings": {
"profile": {
"save": "Save changes",
"greeting": "Hello, {{name}}"
}
}
}
If the project stores msg translation JSON (title / attributes / messages[]), match that shape instead of nested key-value.
MsgResource — after scaffolding with msg-cli, append (or replace CLI samples with) chained .add calls:
resource
.add('settings.profile.save', 'Save changes')
.add('settings.profile.greeting', 'Hello, {name}');
Match placeholder syntax to the project format (MF1 {name} vs MF2 {$name}). See references/FORMATS.md.
4. Replace literals
// before
<button>Save changes</button>
<p>Hello, {name}</p>
// after (typical t() helper)
<button>{t('settings.profile.save')}</button>
<p>{t('settings.profile.greeting', { name })}</p>
For MsgResource-based UIs, follow the project's pattern (e.g. messages.get('key')?.format({ name }) or <MsgMessage … />) instead of inventing a new API.
Ensure the lookup helper is in scope — add the existing import/hook pattern.
5. Verify
- No remaining hard-coded copy in the touched UI paths (unless intentionally left).
- YAML/JSON is valid; MsgResource file still exports a valid resource.
- Placeholder names in the locale file match call-site params.
Examples
Input (component):
export function EmptyState() {
return (
<div>
<h1>No projects yet</h1>
<p>Create your first project to get started.</p>
<button type="button">Create project</button>
</div>
);
}
YAML / nested JSON keys: projects.empty.title, projects.empty.body, projects.empty.cta
MsgResource adds:
resource
.add('projects.empty.title', 'No projects yet')
.add('projects.empty.body', 'Create your first project to get started.')
.add('projects.empty.cta', 'Create project');
Output (component) — adjust to the project's lookup API:
export function EmptyState() {
return (
<div>
<h1>{t('projects.empty.title')}</h1>
<p>{t('projects.empty.body')}</p>
<button type="button">{t('projects.empty.cta')}</button>
</div>
);
}
Additional resources
- Output formats (YAML, JSON, MsgResource): references/FORMATS.md
- Key naming and edge cases: references/KEY-GUIDE.md