"TIK" is an abbreviation for "Textual Internationalization Key". A TIK is simultaneously the source of truth for translation and a unique message identifier within a domain.
TIKs make translation keys human-readable by closely reflecting the actual text shown to the end users in the source code. This improves context for translators, enables programmatic generation of ICU messages, and supports better automation and CI/CD integration.
TIK enables more efficient workflows by integrating TIK processors with CI and LLMs to give developers immediate feedback on i18n issues before they hit production. It reduces costs by minimizing reliance on human translators and eases pressure on them by offloading routine tasks, allowing experts to focus more on quality assurance.
TIK is designed to be agnostic to both programming languages and natural languages used in application source code.
TIP: Check out the official TIK cheatsheet.
Table of Contents
The normative rules for TIK syntax, ICU encoding, and configuration guidelines are maintained in SPECIFICATION.md.
Internationalization (i18n) and localization (l10n) are hard — and most developers avoid them. Supporting multiple languages and regions demands significant effort, expensive tooling, complex error-prone workflows with slow feedback loops, and discipline that many teams are unable to take on.
- Translators often work with vague context, leading to broken translations.
- Messages get over-abstracted for reuse breaking grammar and structure in many languages.
- Automation is limited by missing metadata and pipelines developers lack control over.
- The feedback loop is slow, brittle, and disconnected from CI/CD.
The result is missing or poor i18n and l10n that signals lack of polish, undermines user trust, alienates global audiences and subsequently blocks adoption and growth.
Traditional internationalization relies heavily on key-based systems, where developers assign abstract message identifiers (e.g. "dashboard.report.summary") to translated
strings stored in external files.
i18n.ByKey("dashboard.report.summary", numberOfMessages, dateTime)Keys offer clear benefits, such as:
- Separation of concerns - Developers reference keys, while translators manage the actual text.
- Reusability - the same message can be used across different contexts or interfaces.
- Dynamic updates - translation changes go live immediately without redeployment.
- Integration - keys work seamlessly with most existing localization infrastructure.
However, key-based i18n introduces an abstraction layer between the source code and the actual text, making it harder for developers to immediately understand what message is being displayed - and in what form.
Naming is inherently hard - and coming up with meaningful, consistent translation keys can be difficult, especially at scale. Poorly chosen keys often lead to confusion, redundancy, or fragile reuse patterns.
TIKs, by contrast, embed the meaning directly in the code using a naturally readable and self-explanatory format that serves as source of truth for the i18n pipeline:
reader.String(`You had {# messages} at {time-short}.`, numberOfMessages, dateTime)ICU messages are a powerful internationalization tool but are too complex, unreadable and error-prone when used directly inside the application source code.
Consider the following example in Go:
i18n.Text(`You had {numberOfMessages, plural,
=0 {no messages}
one {# message}
other {# messages}
} at {time, date, jm}.`, numberOfMessages, dateTime)With TIK, developers write simple, readable keys and still get the full power of ICU under the hood.
⚠️ Learning Curve: Developers must learn the TIK syntax and conventions.⚠️ Source of Truth in Code: The TIK in the source code is the source of truth for every translation derived from it. This keeps translations from drifting away from the original intent, but it also means translators cannot fix a poor source TIK directly. Corrections must flow back to developers and be applied in code.⚠️ Language-specific Tooling Requirements: A dedicated extractor tool (referred to as TIK processor through this document) is required to parse and process TIK keys from source code to eventually produce ICU messages for translation.⚠️ Source Language Translation: TIKs with branching (such as plural or gender-dependent forms) cannot produce complete ICU messages and must pass through the translation pipeline too. The TIK only encodes theothercases.⚠️ Static Analysis Scope: Duplicate-TIK detection is limited to what the processor can see in the source code. If a TIK is wrapped in a helper function and reused across call sites, the processor observes only a single declaration and cannot warn about unintended reuse of the returned message in conflicting contexts.
Frequently asked questions are maintained in FAQ.md.
Special thanks to Muthu Kumar (@MKRhere)!