Ink React CLI localization and terminal layout

Ink React CLI localization makes an interactive JavaScript command-line application readable across languages while keeping its commands and records trustworthy. If you are searching for Ink multilingual Text and Box components, Intl or ICU-style messages, useInput keyboard handling, focus management, terminal flexbox wrapping and Unicode release QA, this guide shows what to implement and how to test it.

Ink renders React components into a terminal and uses a Yoga-based layout model; it is not an automatic translation engine. A project chooses a message-catalog solution and may use JavaScript Intl APIs for dates and numbers. Compared with browser React, terminal rendering has stricter column widths, input streams and font limitations, so language-aware layout and keyboard accessibility are essential.

Imagine Archive Compass, a fictional CLI used to organize multilingual oral-history recordings. A researcher may translate the interface label for review required, but the recording’s accession number, original speaker quotation and audit timestamp must remain unchanged. The following chapters show a robust separation between interface messages, terminal interaction and archival evidence.

Quick answer: how to localize Ink React interactive command-line application responsibly

Select a supported framework and integration version, rather than mixing incompatible examples.
Separate interface messages from immutable IDs, user-provided text, audit events and typed records.
Create reviewable message resources with explicit language choice, grammar and fallback.
Make the chosen language a state change that refreshes all visible controls.
Keep keyboard bindings and application actions independent of translated labels.
Test script shaping, Unicode cell width, long text and small terminal sizes.
Check both success and failure outcomes for truthful user-facing messages.
Package all required catalog assets and verify from a clean installation.
Use fluent human review as well as event tests and snapshots.
Release only the languages and terminal combinations that were actually checked.

Who this guide is for

This guide is for software engineers, technical writers, localization managers, open-source maintainers and product teams who need a dependable multilingual terminal application. It assumes that the reader can follow ordinary Ink React interactive command-line application concepts but may be new to the difference between rendering a string and designing a translatable user experience. The examples are educational; exact package signatures should always be checked against the pinned release.

The core translation boundary
A working user journey
Twenty-two implementation decisions
Twenty-four troubleshooting situations
Four-week implementation plan
Frequently asked questions
Official documentation and related guides

The core translation boundary

Ink renders React components in the terminal, but translation catalogs and language choice require a deliberate integration. Recording IDs, timestamps, researcher notes and metadata provenance remain data, not translated UI labels.

A translated interface is a different view of the same task. The safest architecture separates four layers: original records; application decisions and events; message identifiers and values; and terminal rendering. Only the last two layers ordinarily change when the user chooses another language. A value can be formatted differently for readers, but canonical numeric data, identifiers and completed-action records should not be silently overwritten.

For a source string, ask three questions before extraction. Is it something the program itself tells a person? Does its meaning depend on the exact workflow state? Could another person have authored it or used it as an identifier? The first kind belongs in a catalog, the second needs careful message context, and the third usually belongs outside translation. A quotation, file path or record key may be shown next to a localized instruction without becoming a translatable instruction.

This distinction matters across countries because translation changes grammar, date presentation, word order and conventions, not just visible spelling. Never make a promise about work completed unless the event actually succeeded. When an operation is pending, report it as pending; when it fails, identify the recoverable condition without exposing sensitive internal detail. A trustworthy language layer describes the same facts in a voice that readers can understand.

A complete user journey: Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries

Begin with a real task, not a list of isolated buttons. Open the app using a fresh account or test profile; select a non-default language; navigate to one record; make a harmless change; read a confirmation; and export the resulting record. Repeat the journey with a failure introduced at the moment of writing. Your notes should contain what the user saw, what the application attempted, what the system verified and what was persisted.

The practical advantage of this small journey is that it exposes coupled failures. A new locale may be applied to the initial screen but not a modal. A formatted count may be correct until it reaches zero. A confirmation may use a friendly translated verb even though the export failed. A report may retranslate a source quotation or accidentally change a machine-readable property. These problems appear together in an end-to-end test and often disappear when engineers only inspect a catalog.

Record four baseline outcomes: the same item remains selected, the same source values are stored, every visible message follows the selected language or documented fallback, and each action produces the same verified result. Add layout observations at narrow and wide widths. These four outcomes can be checked after every translation update without requiring an entirely new test design.

Twenty-two implementation decisions for Ink React interactive command-line application

The following decisions move from translation boundaries to Ink’s Text and Box components, useInput, useFocus and terminal rendering. They are deliberately sequenced so that a team can validate one working screen before expanding its language catalog. Do not confuse a working message lookup with a complete localization release.

1. Identify messages and protected metadata

Extract screen titles, button hints, prompts, validation errors, export confirmations and help content from React components. Keep accession IDs and source-language testimony outside translation catalogs.

A translated UI must never silently revise an archival record or claim a recording was verified when it was not. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

A reliable place to start is the smallest working screen. Document what the operator believes the control means, the action it triggers, and the stored data it touches. That record gives a translator enough context to preserve intent rather than merely replacing individual words.

Mark every user-authored and machine-authored field in the export journey. For a practical acceptance check, begin with the default-language interface, complete the named task, switch locale without restarting, and repeat it. Observe the new text but compare the same record identity, result state and output artifact. This is more informative than a static screenshot.

2. Pin Ink and React versions

Check the selected Ink release and its supported React and Node requirements. Ink documentation may describe different current and upcoming APIs.

A hook copied from another major version might not work in your installed environment. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Treat implementation and language review as two connected tests. A screen can compile yet mislead a user about whether a command merely started or actually completed. Write the expected state change before adjusting the visible copy, then verify both.

Lock versions and run a minimal terminal render and keyboard test. To make the failure visible early, try one very short translation and one deliberately long one. Use a narrow terminal, keyboard-only input and a non-English script. If the control is clipped or its action changes, the implementation is not ready for release.

3. Choose a message system

Use a suitable library or application-owned catalogs for semantic message IDs, interpolation and plural rules. JavaScript Intl alone formats values, not arbitrary translated prose.

Do not assume Intl.DateTimeFormat will translate a button label such as Submit metadata. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

The difficult part is rarely finding a synonym. It is deciding which representation belongs to the interface and which is an unchanged fact. Make the distinction observable through a tiny example, a negative test, and a second language whose word order differs from English.

Prove a catalog lookup for two locales before building more screens. A reviewer should see the whole interaction, not a detached spreadsheet cell. Present the source, its intended audience, the message context, placeholders and possible error states. Ask the reviewer what action they expect the system to perform from the translated wording.

4. Put language preference in React state

Keep locale as explicit state or context that the component tree can read; avoid mutating a single global translator for unrelated sessions.

A locale toggle must rerender all dependent components, not just the header. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Use a before-and-after run to prevent accidental side effects. Record selected item, user input, result code, terminal width and locale. If changing the language changes any unrelated record value, stop and repair the data boundary before polishing style.

Switch languages inside a half-completed metadata edit and preserve typed values. Record a passing and a failing path. The passing path tests fluency; the failure path tests truthfulness. An honest error must distinguish an unconfirmed operation from an operation completed and stored. This is especially important for irreversible or time-sensitive actions.

5. Use Text for terminal text

Ink requires textual content in Text components while Box supplies layout. Structure nested interface messages accordingly.

Copying browser DOM assumptions into Ink can yield invalid component trees or unexpected rendering. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Render a localized heading, description and inline highlighted field in a minimal test. For a practical acceptance check, begin with the default-language interface, complete the named task, switch locale without restarting, and repeat it. Observe the new text but compare the same record identity, result state and output artifact. This is more informative than a static screenshot.

6. Use Box with flexible widths

Yoga-based terminal layout can arrange columns and rows, but translated strings may wrap and use different cell widths.

A German label may overflow the panel where an English label fits. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Test horizontal and vertical layouts at multiple stdout widths. To make the failure visible early, try one very short translation and one deliberately long one. Use a narrow terminal, keyboard-only input and a non-English script. If the control is clipped or its action changes, the implementation is not ready for release.

7. Account for full-width characters

Terminal glyphs occupy cells rather than CSS pixels; CJK, emoji and combining marks need careful layout testing.

String.length in JavaScript counts UTF-16 code units, not visual columns or user-perceived characters. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Check real terminal rendering against narrow and wide multilingual samples. A reviewer should see the whole interaction, not a detached spreadsheet cell. Present the source, its intended audience, the message context, placeholders and possible error states. Ask the reviewer what action they expect the system to perform from the translated wording.

8. Build complete grammatical messages

Localize full instructions and conditions rather than joining independently translated fragments around variables.

Changing word order for gender, number or politeness can become impossible with fragments. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Review metadata validation messages containing a person, a file and a count. Record a passing and a failing path. The passing path tests fluency; the failure path tests truthfulness. An honest error must distinguish an unconfirmed operation from an operation completed and stored. This is especially important for irreversible or time-sensitive actions.

9. Use Intl for value presentation

Format dates and numbers according to a selected locale, while storing original timestamps and numeric fields in canonical forms.

Formatted display must not become serialized source data by accident. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Compare exported metadata before and after changing UI language. For a practical acceptance check, begin with the default-language interface, complete the named task, switch locale without restarting, and repeat it. Observe the new text but compare the same record identity, result state and output artifact. This is more informative than a static screenshot.

10. Keep archival evidence immutable

Original spoken quotations and accession records are not UI strings. Offer authorized translated summaries as distinct fields with attribution.

Changing a quotation based on the interface locale can falsify source material. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Verify raw transcripts and record IDs remain byte-for-byte equivalent. To make the failure visible early, try one very short translation and one deliberately long one. Use a narrow terminal, keyboard-only input and a non-English script. If the control is clipped or its action changes, the implementation is not ready for release.

11. Use useInput intentionally

Handle keyboard actions through stable identifiers; localize the help text that tells users what keys do.

Pressing Enter or Escape should keep meaning even when a command label changes language. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Exercise navigation without a mouse in every target language. A reviewer should see the whole interaction, not a detached spreadsheet cell. Present the source, its intended audience, the message context, placeholders and possible error states. Ask the reviewer what action they expect the system to perform from the translated wording.

12. Review focus management

Ink offers focus-related hooks and controllers for interactive components. Preserve focus and editing state across locale rerenders.

Reconstructing a focused input can move the cursor and cause accidental submission. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Change language during a form entry, then continue typing and tabbing. Record a passing and a failing path. The passing path tests fluency; the failure path tests truthfulness. An honest error must distinguish an unconfirmed operation from an operation completed and stored. This is especially important for irreversible or time-sensitive actions.

13. Respect paste and composition

Multilingual names and descriptions may arrive through IME or paste events. Inspect current Ink APIs for how input is delivered.

A keystroke-only assumption can corrupt entire pasted strings or non-Latin composition. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Paste Korean, Arabic and accented French samples; compare stored data. For a practical acceptance check, begin with the default-language interface, complete the named task, switch locale without restarting, and repeat it. Observe the new text but compare the same record identity, result state and output artifact. This is more informative than a static screenshot.

14. Keep output streams separate

Interactive frames, stderr diagnostics and machine-readable JSON outputs serve different audiences. Do not translate stable JSON keys.

A translated machine key can break downstream scripts that depend on the export schema. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Pipe output to a file and compare it with interactive TTY rendering. To make the failure visible early, try one very short translation and one deliberately long one. Use a narrow terminal, keyboard-only input and a non-English script. If the control is clipped or its action changes, the implementation is not ready for release.

15. Test non-interactive behavior

Ink can render differently under CI, redirected output and terminal environments. Decide what the app should do without an interactive TTY.

A tool that assumes keyboard input in a pipeline can hang without any way to progress. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Run under CI and redirection and verify useful output and exit status. A reviewer should see the whole interaction, not a detached spreadsheet cell. Present the source, its intended audience, the message context, placeholders and possible error states. Ask the reviewer what action they expect the system to perform from the translated wording.

16. Protect user content from terminal effects

Do not treat imported quotations as styling instructions or allow control sequences to change the screen.

A control character inside archival material can create a false prompt or hide important context. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Use malicious-looking pasted samples in a safe test session and inspect the rendered text. Record a passing and a failing path. The passing path tests fluency; the failure path tests truthfulness. An honest error must distinguish an unconfirmed operation from an operation completed and stored. This is especially important for irreversible or time-sensitive actions.

17. Design error status semantics

Differentiate missing file, invalid metadata, pending upload, rejected export and successful export. Translate precisely.

The message Export complete cannot appear until the output file exists and passes checks. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Inject each error path and compare UI wording with the result returned to the caller. For a practical acceptance check, begin with the default-language interface, complete the named task, switch locale without restarting, and repeat it. Observe the new text but compare the same record identity, result state and output artifact. This is more informative than a static screenshot.

18. Make short labels a separate review task

Some terminal controls need concise translations, but shortening must not erase meaning or consent requirements.

Replacing a meaningful warning with a vague OK label may conceal consequences. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Review both full and short messages with fluent speakers on actual screen widths. To make the failure visible early, try one very short translation and one deliberately long one. Use a narrow terminal, keyboard-only input and a non-English script. If the control is clipped or its action changes, the implementation is not ready for release.

19. Test script compatibility

Real terminals and fonts vary in Unicode shaping, bidi support, emoji width and colour handling.

Correct string content is not proof that an end user can read it on every terminal. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Record supported terminals and provide a plain text or web alternative for hard cases. A reviewer should see the whole interaction, not a detached spreadsheet cell. Present the source, its intended audience, the message context, placeholders and possible error states. Ask the reviewer what action they expect the system to perform from the translated wording.

20. Package translation assets reliably

Ensure message catalogs ship with the published npm package or bundled executable and resolve paths from the installed location.

A source checkout can hide missing files in a release archive. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Install the package in a clean directory and test offline locale switching. Record a passing and a failing path. The passing path tests fluency; the failure path tests truthfulness. An honest error must distinguish an unconfirmed operation from an operation completed and stored. This is especially important for irreversible or time-sensitive actions.

21. Automate visual and behavioral QA

Ink can support rendered-output tests, but snapshots alone do not prove that commands execute correctly or that phrases are natural.

A localized screenshot can pass while Escape deletes an unintended record. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Assert output, state transitions, action identifiers and expected exit codes. For a practical acceptance check, begin with the default-language interface, complete the named task, switch locale without restarting, and repeat it. Observe the new text but compare the same record identity, result state and output artifact. This is more informative than a static screenshot.

22. Publish truthful support claims

List locales, required runtime, terminal limitations and tested input methods; acknowledge partial translations explicitly.

Multilingual support should describe working end-user tasks, not just language flags. Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Run a complete research record creation and export for every promised locale. To make the failure visible early, try one very short translation and one deliberately long one. Use a narrow terminal, keyboard-only input and a non-English script. If the control is clipped or its action changes, the implementation is not ready for release.

Worked implementation: from an English screen to a maintained multilingual release

Phase A: record the baseline

Capture the current source-language screen, data IDs, key bindings and normal end state. Save a simple acceptance transcript showing what a correct interaction looks like. A second person should be able to follow it without knowing the source code. For Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries, compare the localized interface with the unchanged underlying task record and keep a clear note of what was verified.

Phase B: design the catalog

Give each visible sentence a clear purpose and stable context. Capture variable names and units. Use complete messages for counts and conditions; do not ask translators to guess whether a word is a verb, a noun or a hidden system state. For Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries, compare the localized interface with the unchanged underlying task record and keep a clear note of what was verified.

Phase C: introduce locale state

Give language preference a clear owner. Render a complete screen in a target language, then change back while preserving input, selection and identity. If a widget keeps stale wording, update the appropriate state rather than rewriting stored data. For Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries, compare the localized interface with the unchanged underlying task record and keep a clear note of what was verified.

Phase D: challenge the layout

Test 40-column and 80-column arrangements, realistic line wrapping, full-width characters, long translated labels and minimal-colour terminals. A terminal interface must survive these constraints even when every string is grammatically correct. For Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries, compare the localized interface with the unchanged underlying task record and keep a clear note of what was verified.

Phase E: test error truthfulness

Cause a safe simulated failure and check which message appears. Do not say an export succeeded until the artifact exists. Do not say an upload was accepted until acknowledgment is confirmed. Capture the result code separately from its human-language explanation. For Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries, compare the localized interface with the unchanged underlying task record and keep a clear note of what was verified.

Phase F: test installation and language coverage

Install the actual distributable in a clean environment. Check that translation resources are available offline, that unsupported language preferences fall back predictably, and that every claimed supported language completes the same user journey. For Archive Compass, a fictional command-line research assistant that helps staff label oral-history recordings, validate metadata and export catalog summaries, compare the localized interface with the unchanged underlying task record and keep a clear note of what was verified.

Twenty-four real troubleshooting situations

A useful localization problem report includes the requested language, catalog version, executable version, terminal emulator, window dimensions, input method, triggering action and observed result. Without these details, a one-line report such as translation broken is too vague to reproduce. The cases below show where to look and how to prove the repair.

Case 1: Text appears outside a Text component

Browser React markup was copied into a terminal renderer with different component rules. First reproduce the failure with a known catalog, a fixed terminal width and a record whose identifier can be inspected afterward. Write down the visible message and the actual state transition: those two observations tell you whether the fault is in language lookup, layout or application behavior.

Wrap textual nodes in Ink Text and keep layout in Box components. After the repair, restart the installed application, use keyboard input to trigger the same screen, and compare the saved result with its original identifier. The target-language message must describe the observed state and must remain readable when the terminal is resized.

Case 2: English remains after changing language

A component cached its own translated literal outside reactive locale state. Isolate one variable at a time. Try the default language and a target language under the same input and terminal conditions; then change just the terminal width or packaged runtime. This prevents a packaging failure being mistaken for a grammar error.

Use context or state-dependent lookup and test a whole-tree rerender. Acceptance means more than eliminating the screenshot defect. Ask a reader fluent in that language to explain the message and then perform the intended action without coaching. Confirm that nothing in the exported record changes solely because the interface language changed.

Case 3: An Arabic sentence reads incorrectly

The terminal font or bidi behavior is unsupported or inconsistent. Treat the visible symptom as evidence, not as a reason to alter stored data. Inspect how the message was produced, what version of the library was installed, and whether the event completed before the interface made its claim.

Test supported terminals, note limitations and offer readable alternate output. Retest with an intentionally long translation and a non-Latin test value. Also check whether the error stays visible long enough to understand. If a translated warning disappears before the user can respond, the problem is only partly fixed.

Case 4: A Japanese heading breaks a table

The layout treats UTF-16 string length as terminal-cell width. Create a regression test for the particular case before editing the translation. Include an unsuccessful path where one is possible; many serious localization defects occur in error screens that receive little attention during normal use.

Check real display width and use adaptive Box layout. Finally, test both a fresh installation and the normal developer environment. Packaging, font, catalog and terminal settings often hide failures during development. Keep the exact reproducer in the release checklist so the next upgrade cannot silently restore it.

Case 5: A researcher loses an unfinished note

Language switching remounts the form and clears local inputs. First reproduce the failure with a known catalog, a fixed terminal width and a record whose identifier can be inspected afterward. Write down the visible message and the actual state transition: those two observations tell you whether the fault is in language lookup, layout or application behavior.

Preserve editing state across locale changes and restore focus. After the repair, restart the installed application, use keyboard input to trigger the same screen, and compare the saved result with its original identifier. The target-language message must describe the observed state and must remain readable when the terminal is resized.

Case 6: The wrong control receives Enter

Focus was reset during a translation rerender. Isolate one variable at a time. Try the default language and a target language under the same input and terminal conditions; then change just the terminal width or packaged runtime. This prevents a packaging failure being mistaken for a grammar error.

Maintain stable component identity and inspect useFocus behavior. Acceptance means more than eliminating the screenshot defect. Ask a reader fluent in that language to explain the message and then perform the intended action without coaching. Confirm that nothing in the exported record changes solely because the interface language changed.

Case 7: A command label suggests a different key

Translated help text is separated from the actual useInput binding. Treat the visible symptom as evidence, not as a reason to alter stored data. Inspect how the message was produced, what version of the library was installed, and whether the event completed before the interface made its claim.

Render key hints from the binding map and test them. Retest with an intentionally long translation and a non-Latin test value. Also check whether the error stays visible long enough to understand. If a translated warning disappears before the user can respond, the problem is only partly fixed.

Case 8: A pasted quotation changes characters

Input code slices strings by code unit rather than Unicode-aware boundaries. Create a regression test for the particular case before editing the translation. Include an unsuccessful path where one is possible; many serious localization defects occur in error screens that receive little attention during normal use.

Preserve pasted text as data and test grapheme-sensitive editing. Finally, test both a fresh installation and the normal developer environment. Packaging, font, catalog and terminal settings often hide failures during development. Keep the exact reproducer in the release checklist so the next upgrade cannot silently restore it.

Case 9: Machine JSON fields are translated

The export function reuses visible text as serialized property names. First reproduce the failure with a known catalog, a fixed terminal width and a record whose identifier can be inspected afterward. Write down the visible message and the actual state transition: those two observations tell you whether the fault is in language lookup, layout or application behavior.

Keep schema keys stable and translate only human-readable values when allowed. After the repair, restart the installed application, use keyboard input to trigger the same screen, and compare the saved result with its original identifier. The target-language message must describe the observed state and must remain readable when the terminal is resized.

Case 10: An export says complete before writing finishes

UI state updates on the start of an asynchronous operation. Isolate one variable at a time. Try the default language and a target language under the same input and terminal conditions; then change just the terminal width or packaged runtime. This prevents a packaging failure being mistaken for a grammar error.

Wait for confirmed file completion and handle failure separately. Acceptance means more than eliminating the screenshot defect. Ask a reader fluent in that language to explain the message and then perform the intended action without coaching. Confirm that nothing in the exported record changes solely because the interface language changed.

Case 11: An incomplete catalog silently falls back

Message lookup quietly uses default English without coverage reporting. Treat the visible symptom as evidence, not as a reason to alter stored data. Inspect how the message was produced, what version of the library was installed, and whether the event completed before the interface made its claim.

Log missing keys and publish language support limits. Retest with an intentionally long translation and a non-Latin test value. Also check whether the error stays visible long enough to understand. If a translated warning disappears before the user can respond, the problem is only partly fixed.

Case 12: The package cannot find locale JSON

Catalog files were excluded from the npm publish files list or bundle. Create a regression test for the particular case before editing the translation. Include an unsuccessful path where one is possible; many serious localization defects occur in error screens that receive little attention during normal use.

Inspect the release artifact and install from it in a clean directory. Finally, test both a fresh installation and the normal developer environment. Packaging, font, catalog and terminal settings often hide failures during development. Keep the exact reproducer in the release checklist so the next upgrade cannot silently restore it.

Case 13: A non-TTY invocation hangs

Interactive hooks expect input from an unavailable terminal. First reproduce the failure with a known catalog, a fixed terminal width and a record whose identifier can be inspected afterward. Write down the visible message and the actual state transition: those two observations tell you whether the fault is in language lookup, layout or application behavior.

Offer a defined batch mode or fail with a clear, stable exit status. After the repair, restart the installed application, use keyboard input to trigger the same screen, and compare the saved result with its original identifier. The target-language message must describe the observed state and must remain readable when the terminal is resized.

Case 14: CI output differs from an interactive run

Ink adapts rendering outside a TTY and may show only the final frame. Isolate one variable at a time. Try the default language and a target language under the same input and terminal conditions; then change just the terminal width or packaged runtime. This prevents a packaging failure being mistaken for a grammar error.

Test both modes and assert outcomes rather than identical cursor sequences. Acceptance means more than eliminating the screenshot defect. Ask a reader fluent in that language to explain the message and then perform the intended action without coaching. Confirm that nothing in the exported record changes solely because the interface language changed.

Case 15: A date appears in the wrong timezone

Intl formatting used a default timezone without specifying intent. Treat the visible symptom as evidence, not as a reason to alter stored data. Inspect how the message was produced, what version of the library was installed, and whether the event completed before the interface made its claim.

Keep canonical timestamps and state the timezone for archive events. Retest with an intentionally long translation and a non-Latin test value. Also check whether the error stays visible long enough to understand. If a translated warning disappears before the user can respond, the problem is only partly fixed.

Case 16: A plural sentence fails on one item

The message uses English concatenation instead of proper plural categories. Create a regression test for the particular case before editing the translation. Include an unsuccessful path where one is possible; many serious localization defects occur in error screens that receive little attention during normal use.

Use a grammar-aware message formatter and test count boundaries. Finally, test both a fresh installation and the normal developer environment. Packaging, font, catalog and terminal settings often hide failures during development. Keep the exact reproducer in the release checklist so the next upgrade cannot silently restore it.

Case 17: A long French prompt hides Cancel

Fixed Box width prevents translated text from wrapping naturally. First reproduce the failure with a known catalog, a fixed terminal width and a record whose identifier can be inspected afterward. Write down the visible message and the actual state transition: those two observations tell you whether the fault is in language lookup, layout or application behavior.

Use flexible layout and verify cancel remains reachable. After the repair, restart the installed application, use keyboard input to trigger the same screen, and compare the saved result with its original identifier. The target-language message must describe the observed state and must remain readable when the terminal is resized.

Case 18: Raw quotation contains terminal controls

Untrusted content is emitted with executable control sequences. Isolate one variable at a time. Try the default language and a target language under the same input and terminal conditions; then change just the terminal width or packaged runtime. This prevents a packaging failure being mistaken for a grammar error.

Sanitize display and keep source records protected from presentation transformations. Acceptance means more than eliminating the screenshot defect. Ask a reader fluent in that language to explain the message and then perform the intended action without coaching. Confirm that nothing in the exported record changes solely because the interface language changed.

Case 19: Users cannot distinguish warnings in monochrome

The app conveys state only through colour. Treat the visible symptom as evidence, not as a reason to alter stored data. Inspect how the message was produced, what version of the library was installed, and whether the event completed before the interface made its claim.

Add translated labels and inspect low-colour terminals. Retest with an intentionally long translation and a non-Latin test value. Also check whether the error stays visible long enough to understand. If a translated warning disappears before the user can respond, the problem is only partly fixed.

Case 20: A help overlay mixes languages

Some help strings are embedded in third-party components outside catalog lookup. Create a regression test for the particular case before editing the translation. Include an unsuccessful path where one is possible; many serious localization defects occur in error screens that receive little attention during normal use.

Audit every visible component and replace or configure its displayed strings. Finally, test both a fresh installation and the normal developer environment. Packaging, font, catalog and terminal settings often hide failures during development. Keep the exact reproducer in the release checklist so the next upgrade cannot silently restore it.

Case 21: React rerenders while a task is running

Locale state changes during async work and the result message uses stale wording. First reproduce the failure with a known catalog, a fixed terminal width and a record whose identifier can be inspected afterward. Write down the visible message and the actual state transition: those two observations tell you whether the fault is in language lookup, layout or application behavior.

Resolve response state and current locale at the right boundary; never change result semantics. After the repair, restart the installed application, use keyboard input to trigger the same screen, and compare the saved result with its original identifier. The target-language message must describe the observed state and must remain readable when the terminal is resized.

Case 22: An old reference API no longer works

Code was copied from the Ink upcoming-version documentation into an older release. Isolate one variable at a time. Try the default language and a target language under the same input and terminal conditions; then change just the terminal width or packaged runtime. This prevents a packaging failure being mistaken for a grammar error.

Check the actual installed package’s docs and pin compatible methods. Acceptance means more than eliminating the screenshot defect. Ask a reader fluent in that language to explain the message and then perform the intended action without coaching. Confirm that nothing in the exported record changes solely because the interface language changed.

Case 23: An accented name loses its combining mark

Editing code assumes each character is one UTF-16 unit. Treat the visible symptom as evidence, not as a reason to alter stored data. Inspect how the message was produced, what version of the library was installed, and whether the event completed before the interface made its claim.

Test grapheme boundaries and use a Unicode-aware input component or algorithm. Retest with an intentionally long translation and a non-Latin test value. Also check whether the error stays visible long enough to understand. If a translated warning disappears before the user can respond, the problem is only partly fixed.

Case 24: Snapshot tests pass but exports fail

Tests examine visual text without checking files and exit codes. Create a regression test for the particular case before editing the translation. Include an unsuccessful path where one is possible; many serious localization defects occur in error screens that receive little attention during normal use.

Assert output artifacts, metadata integrity and CLI error status separately. Finally, test both a fresh installation and the normal developer environment. Packaging, font, catalog and terminal settings often hide failures during development. Keep the exact reproducer in the release checklist so the next upgrade cannot silently restore it.

A four-week implementation and release plan

Week 1 — scope and preserve behavior

Identify supported locales and complete user journeys. Inventory every visible message and every record that must remain unchanged. Pin exact dependencies. Build one minimal lookup in two languages and capture a baseline test for keyboard actions, storage and terminal size.

Deliverable: a message inventory, a record protection map, working language selection and one reproducible test. A schedule is useful only if the evidence is retained and rechecked when libraries or catalogs change.

Week 2 — complete the critical messages

Translate the primary navigation, confirmation, input guidance, warning and failure pathways. Add grammar-aware count messages and deliberate date and number formatting. Run an in-context review of every action that changes a record, including cancel and retry.

Deliverable: coherent main-task screens, reviewed placeholders and explicit fallback behavior. A schedule is useful only if the evidence is retained and rechecked when libraries or catalogs change.

Week 3 — layout, accessibility and installation

Exercise narrow terminals, wide-character scripts, paste, focus, keyboard navigation, missing assets, monochrome display and redirected output. Install a release build in a clean environment and run it with no access to development directories.

Deliverable: a regression report with actual terminal and platform details, plus a corrected release artifact. A schedule is useful only if the evidence is retained and rechecked when libraries or catalogs change.

Week 4 — validate and communicate support

Ask fluent readers to complete the same real task in each supported language without coaching. Check stored IDs, results, export fields and error semantics after every run. Document unsupported terminals, partial locales and rollback procedure without overstating coverage.

Deliverable: release sign-off for tested language-platform combinations and a repeatable update checklist. A schedule is useful only if the evidence is retained and rechecked when libraries or catalogs change.

Frequently asked questions

Is Ink a website React framework?

No. It is a React renderer for terminal user interfaces, with components such as Text and Box. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

Does Ink translate labels automatically?

No. Add a separate localization system and pass translated messages into components. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

Does JavaScript Intl replace message catalogs?

No. Intl formats dates, numbers and related values; translated UI prose requires message resources. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

Can React context hold the selected language?

Yes. A locale context can keep dependent components synchronized during rerenders. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

Why do CJK labels break alignment?

Full-width terminal characters occupy more visual cells than plain Latin letters. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

How do keyboard shortcuts work with translations?

Use stable input handlers and translate the displayed instructions, not the command identity. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

How do I keep focus after language switching?

Preserve component identity and state, then verify the focus hooks on the actual release. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

Should metadata IDs be translated?

No. Identifiers and source quotations are records; only presentation or separately authorized translations should vary. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

Can users pipe an Ink CLI into scripts?

Only if the application defines stable non-interactive output and does not mix styled frames into machine data. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

How are translations packaged?

Include catalog assets in the npm package or compiled distribution and verify a clean installation. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

Do screenshots prove a translation works?

No. Combine rendered checks with behavior, accessibility, data and native-speaker review. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

What is the safe release test?

Run the complete create-review-export workflow in every promised locale and deployment mode. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

Official documentation and further reading

Library interfaces and compatibility can evolve. Read the current primary documentation and pin the version used by your project; do not assume that an example from a different major version remains correct. Terminal fonts, input systems and screen readers also differ across platforms, so document the actual environments tested.

Continue learning about translation quality

This guide is a platform-specific implementation reference, not a substitute for general research into meaning, register, uncertainty, culture and translation ethics. For that broader foundation, use the translation master. For other technical environments, follow the series index and choose a guide matching your own toolkit.

Master Art of Translation · Translate Like a Pro series index · Longform organization reference · Previous reserved-tens article

Translate Like a Pro | 7420 — Ink React CLI Localization, Intl Messages, Terminal Flexbox, Keyboard Focus and Release QA