Marking text for translation in Angular - Deep Dive

Overview - Marking text for translation

What is it?

Marking text for translation in Angular means identifying parts of your app's text that should be translated into different languages. This helps Angular know which words or sentences to replace when the user changes the language. It involves adding special tags or attributes around text so translation tools can find and manage them easily. This process is the first step to making your app multilingual.

Why it matters

Without marking text for translation, your app would only show one language, limiting who can use it. Marking text lets you prepare your app to speak many languages, making it accessible worldwide. It solves the problem of managing many languages in one place and ensures users see content in their preferred language. Without this, translations would be hard to organize and update, causing confusion and poor user experience.

Where it fits

Before marking text for translation, you should understand Angular components and templates basics. After this, you will learn how to extract marked text into translation files and how to load translations dynamically. Later, you will explore advanced internationalization features like pluralization and date formatting.

Mental Model

Core Idea

Marking text for translation is like putting labels on words so translation tools know exactly what to change when switching languages.

Think of it like...

Imagine you have a photo album with captions in one language. Marking text for translation is like putting sticky notes on each caption that say 'Translate this' so a translator knows which captions to rewrite in another language.

┌───────────────────────────────┐
│ Angular Template              │
│ ┌─────────────────────────┐ │
│ │ <p i18n>Welcome</p>     │ │  <-- Text marked for translation
│ └─────────────────────────┘ │
└───────────────────────────────┘
          ↓
┌───────────────────────────────┐
│ Translation Extraction Tool    │
│ Finds all i18n tags            │
│ Creates translation files      │
└───────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Angular Templates

Concept: Learn what Angular templates are and how text appears in them.

Angular templates are HTML files or inline HTML in components where you write the structure and text of your app's UI. Text inside these templates is what users see on the screen. For example,

Hello

shows the word 'Hello' on the page.

Result

You know where the text lives in Angular apps and why it needs marking for translation.

Understanding where text lives is essential before you can mark it for translation.

2

Foundation

What is Marking Text for Translation

Concept: Introduce the idea of marking text so Angular knows it should be translated.

Marking text means adding a special attribute called i18n to HTML elements or Angular bindings. For example,

Hello

tells Angular this text should be translated. This marking helps tools find and replace text for different languages.

Result

You can mark simple text in templates to prepare for translation.

Knowing how to mark text is the first step to making your app multilingual.

3

Intermediate

Marking Text with Variables and Bindings

🤔Before reading on: do you think you can mark text that includes dynamic variables the same way as static text? Commit to your answer.

Concept: Learn how to mark text that includes dynamic parts like variables or expressions.

When text includes variables, you mark the whole message with i18n and use placeholders for variables. For example:

Hello {{userName}}

. Angular extracts 'Hello {userName}' where {userName} is a placeholder for the variable. This lets translators rearrange or translate the message properly.

Result

You can mark and translate text that changes based on app data.

Understanding placeholders lets you handle real app text, not just fixed words.

4

Intermediate

Using i18n Attributes for Different Elements

🤔Before reading on: do you think i18n works only on text inside tags or also on attributes like titles and labels? Commit to your answer.

Concept: Learn that i18n can mark not only visible text but also attributes like titles, aria-labels, and placeholders.

You can add i18n to attributes by writing i18n-attributeName. For example, marks the button's title attribute for translation. This ensures all user-facing text, visible or not, can be translated.

Result

You can mark all kinds of text, improving accessibility and completeness.

Knowing how to mark attributes ensures no user text is left untranslated.

5

Intermediate

Marking Text in Angular Pipes and Directives

Concept: Understand how to mark text that appears inside Angular pipes or structural directives.

Sometimes text is generated or transformed by pipes or directives. You still mark the original text with i18n. For example,

{{ birthday | date }}

marks the date output for translation context. This helps translators understand the text meaning and format.

Result

You can mark complex text that changes format or content dynamically.

Marking text with pipes ensures translations respect formatting and context.

6

Advanced

Handling Pluralization and ICU Expressions

🤔Before reading on: do you think simple i18n marking handles plurals automatically? Commit to your answer.

Concept: Learn how to mark text that changes based on numbers using ICU message syntax inside i18n tags.

For plurals, you use Angular's ICU syntax inside i18n. Example:

{count, plural, =0 {No items} =1 {One item} other {# items}}

. This tells Angular how to show different messages depending on the count. Translators can adapt these rules for their language.

Result

You can mark and translate text that changes with numbers correctly.

Understanding ICU syntax is key to handling real-world language variations.

7

Expert

Custom IDs and Meaning in i18n Marking

🤔Before reading on: do you think Angular assigns translation IDs automatically or do you need to provide them? Commit to your answer.

Concept: Learn how to add custom meaning and IDs to i18n marks to help translators and avoid conflicts.

By default, Angular generates IDs for marked text, but you can add custom IDs and meanings like

Text

. This helps translators understand context and prevents duplicate translations. It also helps when updating text without breaking translations.

Result

You can manage large translation projects with clarity and fewer errors.

Custom IDs and meanings improve translation quality and maintainability in big apps.

Under the Hood

When Angular compiles your app, it scans templates for i18n attributes. It extracts marked text into translation files (XLIFF or XMB). These files contain original text, placeholders, and metadata. At build or runtime, Angular replaces marked text with translated versions based on the user's language. Placeholders keep dynamic parts intact. The process uses Angular's compiler and runtime i18n services.

Why designed this way?

Angular's i18n system was designed to separate translation from code logic, making it easier to manage languages without changing app code. Using attributes keeps templates readable and allows automated extraction tools. The ICU syntax supports complex language rules. Custom IDs solve problems with ambiguous or repeated text. Alternatives like inline translation would mix code and text, making maintenance harder.

┌───────────────┐       ┌───────────────────────┐       ┌─────────────────────┐
│ Angular       │       │ Extraction Tool       │       │ Translation Files   │
│ Templates    ───────▶│ Finds i18n marks      ───────▶│ XLIFF/XMB with IDs  │
│ (with i18n)   │       │ Extracts text & meta  │       │ Placeholders        │
└───────────────┘       └───────────────────────┘       └─────────────────────┘
         │                                                        │
         │                                                        ▼
         │                                              ┌─────────────────────┐
         │                                              │ Angular Runtime     │
         └─────────────────────────────────────────────▶ Loads translations  │
                                                        │ Replaces marked text │
                                                        └─────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think marking text with i18n automatically translates it at runtime? Commit to yes or no.

Common Belief: Marking text with i18n means Angular will translate it automatically without extra steps.

Reality: Marking text only identifies it for translation. You must extract, translate, and load translation files separately for the app to show translated text.

Why it matters: Without extracting and loading translations, users will still see the original language, causing confusion and a poor experience.

Quick: Do you think you can mark any JavaScript string for translation using i18n? Commit to yes or no.

Common Belief: You can mark any string in Angular code for translation using i18n attributes.

Reality: i18n marking works only in Angular templates, not in TypeScript code. Translating strings in code requires different approaches like runtime translation libraries.

Why it matters: Confusing template marking with code translation leads to untranslated strings and inconsistent UI.

Quick: Do you think the same i18n mark can have different translations in different contexts automatically? Commit to yes or no.

Common Belief: Angular automatically knows the context and translates the same text differently based on where it appears.

Reality: Angular treats identical marked text as the same translation unless you provide custom meaning or IDs to differentiate them.

Why it matters: Without custom IDs, translators may provide wrong translations, harming clarity and user understanding.

Quick: Do you think i18n marking handles plural forms the same way in all languages without extra syntax? Commit to yes or no.

Common Belief: Simple i18n marking automatically handles plurals correctly for all languages.

Reality: You must use ICU plural syntax inside i18n marks to handle plurals properly; otherwise, translations may be incorrect or incomplete.

Why it matters: Ignoring plural rules causes awkward or wrong messages, reducing professionalism and user trust.

Expert Zone

1

Angular's i18n extraction uses message digest hashes by default, which can change if text or whitespace changes, causing translation mismatches unless custom IDs are used.

2

The ICU syntax inside i18n supports not only plurals but also select expressions, enabling gender and other context-sensitive translations.

3

Marking text in nested components requires careful coordination to avoid duplicate or missing translations, especially when using lazy-loaded modules.

When NOT to use

Angular's built-in i18n is not ideal for apps needing runtime language switching or dynamic content translation. In such cases, libraries like ngx-translate are better because they load translations at runtime and support dynamic changes.

Production Patterns

In production, teams mark all user-facing text with i18n attributes, extract translations into XLIFF files, send them to professional translators, and integrate translated files during build. They use custom IDs for ambiguous text and ICU syntax for plurals. Lazy-loaded modules have separate translation files to optimize loading.

Connections

Internationalization (i18n) in Software

Marking text for translation is a foundational step in the broader internationalization process.

Understanding marking text helps grasp how software adapts to multiple languages and cultures systematically.

Localization in Video Games

Both require marking text and assets for translation to provide a native experience to users worldwide.

Seeing how games handle text marking reveals the importance of context and dynamic content in translation.

Linguistics - Context and Meaning

Marking text with meaning and description parallels how linguists analyze context to interpret language correctly.

Knowing this connection highlights why translators need context to produce accurate translations.

Common Pitfalls

#1 Marking text without extracting translations.

Wrong approach:

Hello

Correct approach:

Run Angular extraction tool to create translation files and provide translated versions.

Root cause:

Believing marking alone triggers translation without the extraction and loading steps.

#2 Marking dynamic text incorrectly without placeholders.

Wrong approach:

Hello {{userName}} but treating it as plain text in translation files.

Correct approach:

Use placeholders properly so translators see 'Hello {userName}' and can rearrange if needed.

Root cause:

Not understanding how Angular handles variables inside marked text.

#3 Using i18n on TypeScript strings expecting automatic translation.

Wrong approach:

const greeting = $localize`Hello`; // expecting Angular template i18n to translate this automatically

Correct approach:

Use Angular's $localize for code strings and manage translations separately from template i18n.

Root cause:

Confusing template i18n marking with code string translation mechanisms.

Key Takeaways

Marking text for translation in Angular uses the i18n attribute to identify what should be translated.

This marking is only the first step; you must extract, translate, and load translations for them to appear in the app.

Angular supports complex language needs like variables, plurals, and context through placeholders and ICU syntax.

Custom IDs and meanings help avoid translation errors and improve clarity in large projects.

Angular's i18n is best for compile-time translation; for runtime language switching, other libraries are more suitable.