TIK - Textual Internationalization Key

"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, in the source code, the actual text shown to end users. 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

• Specification
• Problem
  • Problem: Translators often work with vague context, leading to broken translations.
  • Problem: Messages get over-abstracted for reuse, breaking grammar and structure in translations.
  • Problem: Automation is limited by missing metadata and pipelines developers lack control over.
  • Problem: The feedback loop is slow, brittle, and disconnected from CI/CD.
  • Key-based Translation
  • ICU Messages
• Limitations
• FAQ
• Special Thanks

Specification

The normative rules for TIK syntax, ICU encoding, and configuration guidelines are maintained in SPECIFICATION.md.

Problem

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.

Poor i18n/l10n signals lack of polish, undermines user trust, alienates global audiences and subsequently blocks adoption and growth.

Problem: Translators often work with vague context, leading to broken translations.

For example, a lone button labeled Book gives the translator no clue whether it means the noun (something you read) or the verb (to reserve a room) - different words in most languages - so a translator who can't see how it's used can easily pick the wrong one.

Problem: Messages get over-abstracted for reuse, breaking grammar and structure in translations.

For example, a phrase like red car might be split into a reusable red fragment and a reusable car fragment and concatenated in code as red + car. This reads fine in English, but the translator only ever sees the two pieces in that fixed order — so in French, where the adjective follows the noun (voiture rouge), the concatenation is stuck producing the wrong order rouge voiture.

Problem: Automation is limited by missing metadata and pipelines developers lack control over.

For example, a message like {user} shared a photo looks complete in English, but a Russian translation needs to know the sharer's gender — поделился for a man, поделилась for a woman. If the {user} argument passed to the translation reader is just a plain string with no gender attached, no amount of tooling can produce grammatically correct Russian: the program is simply missing the input it needs.

Problem: The feedback loop is slow, brittle, and disconnected from CI/CD.

For example, the code passes two arguments but the translated German string references a third placeholder {count} that was never supplied. Because translations are just strings loaded at runtime, CI stays green and the build ships — the bug only surfaces as a crash, or worse: a raw {count} on screen, for German users in production.

Key-based Translation

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

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.

Limitations

• ⚠️ 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 a TIK processor throughout 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 the other case.
• ⚠️ 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.

FAQ

Frequently asked questions are maintained in FAQ.md.

Special Thanks

Special thanks to Muthu Kumar (@MKRhere)!