Forem: Anton Antonov

Flutter Localization Done Right: ARB Files, Pluralization, and Automated Translations

Anton Antonov — Tue, 10 Mar 2026 12:43:32 +0000

Flutter’s built-in localization system uses Application Resource Bundle (ARB) files and the intl package to deliver fully native experiences in any language. This guide covers everything from project setup and ARB format details to language switching, pluralization, and automating translations with l10n.dev.

What is Flutter Localization?

Flutter localization is the official approach to adapting your app for multiple languages and regions. It relies on ARB files to store translated strings and the flutter_gen code generator to produce type-safe Dart accessors. At runtime, Flutter selects the correct ARB file based on the device locale — no restart required when switching locales programmatically.

Project Setup

Flutter's localization pipeline is driven by two configuration files: pubspec.yaml and l10n.yaml. Enable code generation in pubspec.yaml and point Flutter to your ARB directory.

1. Update pubspec.yaml

Add flutter_localizations and intl as dependencies, then enable the generate flag so Flutter auto-generates the Dart localization classes from your ARB files.

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: any

flutter:
  generate: true

2. Create l10n.yaml

Place an l10n.yaml file at the root of your project to configure the ARB directory, the template file, and the generated output file name.

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

The ARB File Format

ARB (Application Resource Bundle) is a JSON-based format designed specifically for Flutter internationalization. Each key maps to a translatable string, and optional metadata keys (prefixed with @) carry descriptions, placeholder definitions, and context for translators.

@@locale: Declares the locale for the file (e.g., "en", "fr", "zh_CN"). l10n.dev automatically updates this to the target language code.
@@last_modified: Timestamp of the last modification. l10n.dev automatically sets this to the current UTC timestamp when generating translated files.
@key metadata: Metadata entries such as description, example, and placeholders are NOT translated by default - they remain unchanged to preserve context for translators. Enable the translateMetadata setting if you want these translated.
Placeholders and ICU messages: Strings can contain named placeholders ({name}) and ICU message syntax for pluralization and selection - all of which are preserved correctly during translation.

Source ARB file (English)

{
  "@@locale": "en",
  "@@last_modified": "2026-01-15T10:30:00Z",

  "appTitle": "My App",
  "@appTitle": {
    "description": "The title of the application"
  },

  "welcome": "Welcome, {name}!",
  "@welcome": {
    "description": "Welcome message shown on the home screen",
    "placeholders": {
      "name": {
        "type": "String",
        "example": "Alice"
      }
    }
  },

  "unreadMessages": "{count, plural, =0{No unread messages} =1{1 unread message} other{{count} unread messages}}",
  "@unreadMessages": {
    "description": "Number of unread messages",
    "placeholders": {
      "count": {
        "type": "int"
      }
    }
  }
}

Translated ARB file (French)

After translation, UI strings are localized while metadata structure remains intact. l10n.dev updates @@locale and @@last_modified automatically.

{
  "@@locale": "fr",
  "@@last_modified": "2026-01-15T10:30:01Z",

  "appTitle": "Mon Application",
  "@appTitle": {
    "description": "The title of the application"
  },

  "welcome": "Bienvenue, {name} !",
  "@welcome": {
    "description": "Welcome message shown on the home screen",
    "placeholders": {
      "name": {
        "type": "String",
        "example": "Alice"
      }
    }
  },

  "unreadMessages": "{count, plural, =0{Aucun message non lu} =1{1 message non lu} other{{count} messages non lus}}",
  "@unreadMessages": {
    "description": "Number of unread messages",
    "placeholders": {
      "count": {
        "type": "int"
      }
    }
  }
}

File Naming Conventions

ARB files follow a straightforward naming pattern: a prefix (by default app_) followed by the locale code and the .arb extension. Flutter and l10n.dev use underscores to separate language and region codes.

ARB files use underscores, not hyphens - write app_en_US.arb and app_zh_CN.arb, not app_en-US.arb or app_zh-CN.arb.

# Default pattern (recommended)
app_en.arb
app_fr.arb
app_en_US.arb          # Locale with region (underscore format)
app_zh_CN.arb          # Chinese Simplified

# Custom prefix patterns also supported
my_app_en.arb
my_app_fr.arb

# Note: ARB files use underscores, not hyphens
# ✓  app_en_US.arb
# ✗  app_en-US.arb

Project Structure

Organize all your ARB files inside a dedicated l10n folder within lib/. Flutter's code generator picks them up automatically based on the arb-dir setting in l10n.yaml, and outputs ready-to-use Dart classes.

lib/
├── l10n/
│   ├── app_en.arb        ← Source (English)
│   ├── app_fr.arb        ← French
│   ├── app_de.arb        ← German
│   ├── app_ja.arb        ← Japanese
│   ├── app_zh_CN.arb     ← Chinese Simplified
│   └── app_es.arb        ← Spanish
├── main.dart
└── ...

# Generated output (do not edit manually)
.dart_tool/
└── flutter_gen/
    └── gen_l10n/
        └── app_localizations.dart

Initialization

Wire up the generated Dart localization class with MaterialApp by providing the localizationsDelegates and supportedLocales. Flutter will then resolve the correct ARB data for the device locale.

MaterialApp Setup

Pass the four required delegates - your generated AppLocalizations.delegate plus the three Flutter SDK delegates - and list every locale your app supports. Use AppLocalizations.of(context)! anywhere in the widget tree to access translated strings.

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',

      // Required delegates
      localizationsDelegates: const [
        AppLocalizations.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],

      // Supported locales
      supportedLocales: AppLocalizations.supportedLocales,

      home: const HomePage(),
    );
  }
}

// Use in a widget
class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    final l10n = AppLocalizations.of(context)!;

    return Scaffold(
      appBar: AppBar(title: Text(l10n.appTitle)),
      body: Center(child: Text(l10n.welcome('Alice'))),
    );
  }
}

Language Switching at Runtime

Flutter allows you to switch the app locale at runtime by updating the locale property on MaterialApp. A common pattern is to hold a Locale in a StatefulWidget or a state management solution and expose a callback to change it. The widget tree automatically rebuilds with the new locale.

// Manage locale state at the app level
class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  Locale _locale = const Locale('en');

  void _changeLocale(Locale locale) {
    setState(() => _locale = locale);
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      locale: _locale,
      localizationsDelegates: const [
        AppLocalizations.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],
      supportedLocales: AppLocalizations.supportedLocales,
      home: SettingsPage(onLocaleChange: _changeLocale),
    );
  }
}

// Language selector widget
class LanguageSelector extends StatelessWidget {
  final void Function(Locale) onLocaleChange;

  const LanguageSelector({super.key, required this.onLocaleChange});

  @override
  Widget build(BuildContext context) {
    return DropdownButton<Locale>(
      value: Localizations.localeOf(context),
      items: AppLocalizations.supportedLocales
          .map((locale) => DropdownMenuItem(
                value: locale,
                child: Text(locale.toLanguageTag()),
              ))
          .toList(),
      onChanged: (locale) {
        if (locale != null) onLocaleChange(locale);
      },
    );
  }
}

Pluralization

Flutter uses ICU message syntax for pluralization inside ARB files. The intl package handles all CLDR plural categories, automatically applying the correct form based on the target language rules.

Use {count, plural, =0{...} =1{...} other{...}} syntax inside ARB string values.
Declare the count placeholder with type int in the @key metadata.
l10n.dev generates all required plural forms for each target language - including complex languages such as Arabic, Russian, and Polish - without manual intervention.

{
  "cartItems": "{count, plural, =0{Your cart is empty} =1{1 item in your cart} other{{count} items in your cart}}",
  "@cartItems": {
    "description": "Cart item count",
    "placeholders": {
      "count": { "type": "int" }
    }
  },

  "daysLeft": "{days, plural, =1{1 day left} other{{days} days left}}",
  "@daysLeft": {
    "description": "Days remaining",
    "placeholders": {
      "days": { "type": "int" }
    }
  }
}

Full ARB Support in l10n.dev

l10n.dev is purpose-built to work seamlessly with Flutter's ARB workflow. Upload your source ARB file and receive accurate, correctly-structured translations back:

Automatic Metadata Updates: @@locale is updated to the target language code and @@last_modified is set to the current UTC timestamp automatically.
Metadata Translation Control: By default, @key metadata entries (description, example, context) are NOT translated and remain unchanged, keeping translator notes intact. Enable the translateMetadata setting to translate them alongside UI strings.
Custom File Prefixes: Any naming pattern is supported - app_en.arb, my_app_en_US.arb, strings_fr.arb, and more.
Underscore Locale Format: ARB locale codes use underscores (en_US, zh_CN) instead of hyphens - l10n.dev handles this correctly so generated files drop straight into your Flutter project.
Pluralization Aware: ICU plural forms are generated for every target language according to CLDR rules, so no manual plural editing is needed after translation.

Automate Translations with npm

Use the ai-l10n npm package to translate your source ARB file from the command line or as part of a CI/CD pipeline. Install once, then translate to any number of languages in a single command.

# Install the CLI
npm install ai-l10n

# Translate your source ARB to multiple languages
npx ai-l10n translate lib/l10n/app_en.arb \
  --languages fr,de,ja,zh_CN,es,ko

Integration into a Flutter Build

You can wire ai-l10n directly into your Flutter build process so translations are always up to date before the app is compiled. Two common approaches are a package.json script or a Makefile.

Via package.json scripts

Add a translate script and use npm's prebuild lifecycle hook to run it automatically before every build. Run npm run build:android (or build:ios / build:web) and ai-l10n will translate first, then hand off to Flutter.

{
  "scripts": {
    "translate": "ai-l10n translate lib/l10n/app_en.arb --languages fr,de,ja,zh_CN,es,ko --update",
    "prebuild": "npm run translate",
    "build:android": "flutter build apk",
    "build:ios": "flutter build ios",
    "build:web": "flutter build web"
  }
}

Via Makefile

If your team uses Make, declare a translate target and make each build target depend on it. Running make build-android (or build-ios / build-all) will translate all target languages before invoking flutter build.

LANGUAGES = fr,de,ja,zh_CN,es,ko

translate:
    npx ai-l10n translate lib/l10n/app_en.arb --languages $(LANGUAGES) --update

build-android: translate
    flutter build apk

build-ios: translate
    flutter build ios

build-web: translate
    flutter build web

build-all: translate
    flutter build apk
    flutter build ios
    flutter build web

For CI/CD integration, incremental updates, batch translation across multiple files, and GitHub Actions workflow examples, see the Localization Automation Guide.

VS Code Extension

The l10n.dev VS Code extension brings Flutter ARB translation directly into your editor. Right-click any ARB file and translate it to your target languages without leaving VS Code. Get the VS Code Extension for ARB files translation.

How It Works in VS Code:

Open your source ARB file (e.g., app_en.arb) in the editor.
Right-click in the editor and select "Translate JSON".
Choose one or more target languages (e.g., French, Japanese, German).
The extension creates localized ARB files alongside your source, with @@locale and @@last_modified updated automatically.

See It in Action

Here's a live example of translating a Flutter ARB file to Uzbek inside VS Code:

Ready to reach global users? You can translate ARB files directly in the l10n.dev workspace, automate translation with the npm CLI, or translate right inside VS Code. Thanks for reading!

Pseudo-localization for Automated i18n Testing

Anton Antonov — Tue, 23 Dec 2025 10:02:31 +0000

Pseudo-localization is a powerful testing technique that transforms your source text into a fake language to identify internationalization (i18n) issues before actual translation begins. This guide shows you how to automate pseudo-localization testing using the pseudo-l10n npm package.

What is Pseudo-localization?

Pseudo-localization is the process of transforming your application’s source text into an altered, fake language that mimics how UI behaves after translation. It helps QA engineers and developers identify i18n issues early in the development cycle.

Example of using pseudo-localization to identify potential internationalization issues. The font and size are identical on both sides, but supporting other scripts often requires more space.

Why Pseudo-localization is Useful

Pseudo-localization helps you catch i18n issues early:

Exposes layout breakages caused by text expansion (German and Finnish are typically 30–40% longer than English).
Surfaces encoding issues by adding accented characters to test UTF-8 support.
Ensures all strings are translatable — hard-coded text remains unchanged and is easy to spot.
Reveals placeholder mishandling — dynamic content like {{name}} must be preserved.
Helps define translation length limits for UI components with space constraints.

Automation Strategies for QA

Here are proven strategies to automate i18n testing with pseudo-localization:

Accented & Non-Latin Characters

Replace Latin letters with accented forms or different scripts to test character encoding and font support.
Example: “Save” → “Šàvē”
QA check: Ensure all characters display correctly and nothing breaks due to encoding issues.

Text Expansion Simulation

Automatically expand each string by ~30–40% to mimic long languages like German or Finnish. Wrap with visual markers for easy clipping detection.
Example: “Save” → ⟦Šàvēēēēē⟧
QA check: Use automated screenshot comparison to spot UI overflow, clipping, or misalignment.

Placeholder Stress Testing

Replace interpolation variables (placeholders) with visible markers to verify they’re preserved during translation.
Example: “You have {{count}} items” → “You have items”
QA check: Run regression tests; fail if a marker is missing or incorrectly escaped (<COUNT>).

RTL Simulation

Wrap text in right-to-left (RTL) markers using Unicode control characters to simulate Arabic or Hebrew.
QA check: Verify alignment, text direction, and mirroring are correct for RTL languages.

CI/CD Integration

Add pseudo-localization to your automated test pipeline to catch i18n issues before they reach production.
QA check: Block deployment if tests detect missing translations, broken placeholders, or layout issues.

Automating with pseudo-l10n Package

The pseudo-l10n npm package automates pseudo-localization for your JSON translation files, making it easy to integrate i18n testing into your development workflow.

Key Features

Text Expansion: Simulates how translated text is often 30–40% longer than English.
Accented Characters: Tests UTF-8 encoding and font support with accented equivalents.
Visual Markers: Wraps strings with ⟦…⟧ markers to easily spot untranslated or truncated text.
Placeholder Handling: Preserves placeholders like {{name}}, {count}, %key%, etc.
RTL Simulation: Simulates Right-to-Left languages using Unicode control characters.

Installation

Install pseudo-l10n globally for command-line usage:

npm install -g pseudo-l10n

Or add it as a development dependency:

npm install --save-dev pseudo-l10n

Basic Usage

Transform your source translation file into a pseudo-localized version:

pseudo-l10n input.json output.json

Example Transformation
Input (en.json):

{
  "welcome": "Welcome to our application",
  "greeting": "Hello, {{name}}!",
  "itemCount": "You have {{count}} items"
}

Output (pseudo-en.json):

{
  "welcome": "⟦Ŵëļçõɱë ţõ õür àƥƥļïçàţïõñēēēēēēēēēēēēēēēēēē⟧",
  "greeting": "⟦Ĥëļļõēēēēēē, {{name}}!ēēēēē⟧",
  "itemCount": "⟦Ŷõü ĥàṽë {{count}} ïţëɱšēēēēēēēēēēēēēēēē⟧"
}

Advanced Features

Custom Expansion

pseudo-l10n en.json pseudo-en.json --expansion=30

RTL Simulation

Simulate right-to-left languages like Arabic or Hebrew:

pseudo-l10n en.json pseudo-en.json --replace-placeholders

# Input:  { "greeting": "Hello, {{name}}!" }
# Output: { "greeting": "⟦Ĥëļļõēēēēēē, <NAME>!ēēēēē⟧" }

Support for Different Placeholder Formats
The package supports various placeholder formats used by different i18n libraries:

# For i18next (default)
pseudo-l10n en.json pseudo-en.json --placeholder-format="{{key}}"

# For Angular/React Intl
pseudo-l10n en.json pseudo-en.json --placeholder-format="{key}"

# For sprintf style
pseudo-l10n en.json pseudo-en.json --placeholder-format="%key%"

Programmatic Usage

Use pseudo-l10n programmatically in your Node.js scripts or build process:

const { generatePseudoLocaleSync, pseudoLocalize } = require('pseudo-l10n');

// Generate a pseudo-localized JSON file
generatePseudoLocaleSync('en.json', 'pseudo-en.json', {
  expansion: 40,
  rtl: false
});
// Pseudo-localize a single string
const result = pseudoLocalize('Hello, {{name}}!');
console.log(result);
// Output: ⟦Ĥëļļõēēēēēēēēēēēēēē, {{name}}!ēēēēē⟧

Integration into Your Workflow

npm Scripts
Add pseudo-localization generation to your package.json scripts:

{
  "scripts": {
    "pseudo": "pseudo-l10n src/locales/en.json src/locales/pseudo-en.json",
    "pseudo:rtl": "pseudo-l10n src/locales/en.json src/locales/pseudo-ar.json --rtl"
  }
}

Build Process Integration
Generate pseudo-locales as part of your build process:

// build.js
const { generatePseudoLocaleSync } = require('pseudo-l10n');

// Generate pseudo-locales as part of build
generatePseudoLocaleSync(
  './src/locales/en.json',
  './src/locales/pseudo-en.json',
  { expansion: 40 }
);
generatePseudoLocaleSync(
  './src/locales/en.json',
  './src/locales/pseudo-ar.json',
  { rtl: true }
);

CI/CD Pipeline Integration
Integrate pseudo-localization into your continuous integration pipeline:

# .github/workflows/test.yml
- name: Generate pseudo-locales
  run: |
    npm install -g pseudo-l10n
    pseudo-l10n src/locales/en.json src/locales/pseudo-en.json

- name: Run i18n tests
  run: npm run test:i18n

Testing Strategy

Generate pseudo-locale during your build process.
Add pseudo-locale to your application (e.g., in the language selector).
Test your application with pseudo-locale enabled.
Review the application for common i18n issues.

What to Look For

Missing ⟦⟧ markers = untranslated strings (hard-coded text).
Cut-off markers = text truncation or UI overflow.
Broken layout = insufficient space for text expansion.
Garbled text = encoding issues or missing font support.
Wrong text direction = RTL problems (for RTL pseudo-locales).

Pseudo-localization is an essential testing technique that helps you catch internationalization issues before they reach production. By automating pseudo-localization testing with the pseudo-l10n package, you can ensure your application is truly ready for global audiences.

From Testing to Real Translation

Once you’ve validated your i18n implementation with pseudo-localization, it’s time to translate your application for real users. This is where AI-powered translation services like l10n.dev come in.

Why l10n.dev for Production Translation

After ensuring your app handles internationalization correctly with pseudo-localization, use l10n.dev for professional AI-powered translation:

Preserves placeholders, format, and structure — just like pseudo-l10n protects during testing.
Supports 165 languages with context-aware AI translation.
Handles plural forms, interpolation, and special characters automatically.
Provides CI/CD integration via API, npm package ai-l10n, or GitHub Action for automated localization.
Offers VS Code extension and web UI for manual i18n translation.

Complete i18n Workflow

Test your i18n implementation with pseudo-l10n to catch issues early.
Fix any layout, encoding, or placeholder issues discovered during testing.
Translate i18n files using l10n.dev for production-ready translations.

Thanks for reading!

A Cleaner Way to Do i18n in Angular: i18next + Type Safety + Dynamic JSON Imports

Anton Antonov — Tue, 16 Dec 2025 10:01:53 +0000

Internationalization (i18n) is essential for building global Angular applications. This guide shows you how to implement i18next in Angular with proper resource loading, initialization, and usage patterns.

Why i18next for Angular?

i18next is one of the most popular i18n frameworks, offering powerful features and flexibility:

Framework agnostic — works seamlessly with Angular, React, Vue, and others.
Powerful interpolation, pluralization, and context support.
Lazy loading and code splitting support.
TypeScript support with type safety.
Large ecosystem with plugins and extensions.

Installation

Install i18next using npm or yarn:

npm install i18next

That’s it! i18next is a standalone library with no framework-specific dependencies. You don’t need angular-i18next or any other wrapper — just use i18next directly in your Angular application.

Loading Translation Resources

There are two main approaches to loading translation resources in Angular with i18next:

Dynamic Imports (Recommended)

Using dynamic imports leverages Webpack’s code splitting to load translations on-demand. This approach is ideal for applications with many languages or large translation files.

Advantages:

Bundle size optimization — only load needed translations.
Better performance — faster initial load time.
Works perfectly with SSR and prerendering.
No additional HTTP requests required.

Example: Loading with Dynamic Imports

private async loadLanguageResources(
  lang: string,
): Promise<Record<string, Record<string, unknown>>> {
  const languageResources: Record<string, Record<string, unknown>> = {};

  // Load all namespaces for the given language in parallel
  await Promise.all(
    NAMESPACES.map(async (namespace) => {
      const translationModule = await this.loadJson(lang, namespace);
      languageResources[namespace] = translationModule.default;
    }),
  );
  return languageResources;
}

private async loadJson(
  language: string,
  namespace: string,
): Promise<{ default: Record<string, unknown> }> {
  // Webpack automatically code-splits this into separate chunks
  return import(`../../i18n/${language}/${namespace}.json`);
}

This approach imports translation files as ES modules, allowing Webpack to automatically code-split them into separate chunks that are loaded on demand.

i18next-http-backend

The HTTP backend plugin loads translations via HTTP requests from a server or CDN. This is useful when you want to update translations without rebuilding your app.

Advantages:

Update translations without redeployment.
Load translations from external CDN.
Useful for runtime translation management.

Disadvantages:

Additional HTTP requests slow down initial load.
Requires network connectivity.
More complex SSR setup.

Example: Loading with HTTP Backend

import HttpBackend from 'i18next-http-backend';

await init({
  lng: initialLanguage,
  fallbackLng: DEFAULT_LANGUAGE,
  backend: {
    loadPath: '/assets/i18n/{{lng}}/{{ns}}.json',
  },
  use: [HttpBackend],
  ns: NAMESPACES,
  defaultNS: DEFAULT_NAMESPACE,
});

This approach fetches translation files from a server at runtime. Note that this requires additional configuration for SSR.

Which Approach to Choose?

Use Dynamic Imports when:

You want optimal bundle size and performance.
Translations are part of your build process.
You need SSR/prerendering support.

Use HTTP Backend when:

You need to update translations without redeployment.
Translations are managed externally.
You have a CDN for serving translation files.

Proper i18next Initialization

Initializing i18next correctly is crucial for avoiding runtime errors and ensuring translations are available when your app renders.

Using provideAppInitializer

Angular’s provideAppInitializer function (introduced in Angular 18) ensures i18next is fully initialized before the application starts rendering. The provided function is executed during app bootstrap, and initialization does not complete until the Promise resolves. This prevents translation keys from appearing instead of translated text.

Example: App Initializer Configuration

export const appConfig: ApplicationConfig = {
  providers: [
    // ... other providers
    provideAppInitializer(initializeI18n),
    // ... more providers
  ],
};

Why This Matters:

The function runs in the injection context during application startup.
Prevents flickering or showing translation keys on initial load.
Ensures translations are available in all components from the start.
Works correctly with SSR, prerendering, and client-side rendering.

i18next Initialization Function

The initialization function handles loading resources and configuring i18next settings.

Example: I18next Initialization

public async initializeI18n(): Promise<void> {
  const initialLanguage = this.getInitialLanguage();
  const resources: Record<string, Record<string, Record<string, unknown>>> = {};

  if (isPlatformBrowser(this.platformId)) {
    // Browser: Only load the specific language needed
    const languageResources = await this.loadLanguageResources(initialLanguage);
    resources[initialLanguage] = languageResources;
  } else {
    // SSR: Load all languages for prerendering
    for (const lang of SUPPORTED_LANGUAGES) {
      const languageResources = await this.loadLanguageResources(lang);
      resources[lang] = languageResources;
    }
  }

  await init({
    lng: initialLanguage,
    fallbackLng: DEFAULT_LANGUAGE,
    resources,
    ns: NAMESPACES,
    defaultNS: DEFAULT_NAMESPACE,
    interpolation: {
      escapeValue: false,
    },
  });
}

Key points:

Load only the current language in browser for optimal performance.
Load all languages during SSR for prerendering support.
Use fallbackLng to handle missing translations gracefully.
Configure namespaces for better organization.

Translation Pipe

The Angular translation pipe provides a clean way to use translations in templates.

Pipe Implementation

Example: Translation Pipe

import { Pipe, PipeTransform } from '@angular/core';
import { t } from 'i18next';

@Pipe({
  name: 't',
  standalone: true,
  pure: false, // Need to update when language changes
})
export class TranslatePipe implements PipeTransform {
  transform(key: string, options?: Record<string, unknown>): string {
    return t(key, options);
  }
}

The pipe is marked as pure: false to ensure it updates when the language changes. This is important because language changes don’t modify the translation key itself.

Using the Translation Pipe

In Templates:

<!-- With namespace -->
<p>{{ "common:welcomeMessage" | t }}</p>

<!-- With nested keys -->
<p>{{ "dashboard.title" | t }}</p>

<!-- Simple interpolation -->
<p>{{ "greeting" | t: { name: userName } }}</p>
<!-- Result: "Hello, John!" from greeting: "Hello, {{name}}!" -->

<!-- With Angular pipes -->
<p>{{ "price" | t: { amount: 29.99 | currency } }}</p>
<!-- Result: "Price: $29.99" from: "Price: {{amount}}" -->

<!-- Multiple variables -->
<p>{{ "updated" | t: { date: lastModified | date, user: currentUser } }}</p>
<!-- Result: "Updated on Jan 15, 2024 by Alice" from: "Updated on {{date}} by {{user}}." -->

Interpolation allows you to insert dynamic values into your translations. You can pass variables, use Angular pipes for formatting, and combine multiple values in a single translation string.

In Component Code:

import { Component } from '@angular/core';
import { t } from 'i18next';

@Component({
  selector: 'app-dashboard',
  template: `
    <h1>{{ title }}</h1>
    <p>{{ welcomeMsg }}</p>
  `,
})
export class DashboardComponent {
  title = t('dashboard.title');
  welcomeMsg = t('greeting', { name: 'John' });
}

Best Practices for Angular i18next

Use Meaningful Keys

Use dot notation that reflects your app structure: ‘auth:login.title’ instead of ‘loginTitle’ or raw text.

Organize with Namespaces

Split translations into logical namespaces (e.g., common.json, auth.json, dashboard.json) for better maintainability.

Handle Pluralization

Use i18next’s built-in pluralization support for handling singular/plural forms correctly in all languages.

Wait for Initialization

Always ensure i18next is initialized before rendering your app using provideAppInitializer() to run initialization during app bootstrap.

Type Safety for Translation Keys

Use TypeScript to extract translation keys directly from your JSON files for complete type safety. Instead of manually maintaining type definitions, leverage TypeScript’s typeof and dynamic imports to automatically generate types from your actual translation files.

Define a type that extracts all possible keys from your JSON translation files using a recursive NestedKeys helper type.

import common from './en/common.json'; // defaultNS: DEFAULT_NAMESPACE,
import auth from './en/auth.json'; // namespaces

type NestedKeys<T, Prefix extends string = ''> = T extends object
  ? {
      [K in keyof T & (string | number)]: T[K] extends object
        ?
            | NestedKeys<T[K], `${Prefix}${K & (string | number)}.`>
            | `${Prefix}${K & (string | number)}`
        : `${Prefix}${K & (string | number)}`;
    }[keyof T & (string | number)]
  : never;

export type TranslationKey =
  | `common:${NestedKeys<typeof common>}`
  | `auth:${NestedKeys<typeof auth>}`;

Change the pipe’s transform method to accept TranslationKey instead of string. This provides type safety in templates and ensures only valid translation keys can be used.

import { Pipe, PipeTransform } from '@angular/core';
import { t } from 'i18next';

import { TranslationKey } from '../../i18n/translation-key';

@Pipe({
  name: 't',
  standalone: true,
  pure: false, // Need to update when language changes
})
export class TranslatePipe implements PipeTransform {
  transform(key: TranslationKey, options?: Record<string, unknown>): string {
    return t(key, options);
  }
}

Now you get full IntelliSense autocomplete and compile-time errors for invalid keys in both TypeScript code and templates.

t('common:greeting');       // ✅ Autocomplete
t('auth:login.title');      // ✅ Valid
t('invalid.key');           // ❌ IDE shows error

{{ "common:greeting" | t }} // ✅ Valid in templates
{{ "invalid.key" | t }}     // ❌ IDE shows error

Benefits of Type-Safe Translation Keys:

Autocomplete in your IDE for all available translation keys across all namespaces.
Compile-time errors if you use a non-existent key, catching typos before runtime.
Refactoring support — rename keys safely across your entire codebase.
Zero runtime overhead — types are completely removed during compilation.
Auto-generated from your actual JSON files — no manual type maintenance required.

Language Detection and Switching

Implement intelligent language detection and allow users to switch languages at runtime with automatic resource loading.

Determine the user’s language to use when your app starts by checking multiple sources in priority order.

private getInitialLanguage(): string {
  if (isPlatformBrowser(this.platformId)) {
    // Try to get language from localStorage (user preference)
    const savedLang = localStorage.getItem('language');
    if (savedLang) {
      return savedLang;
    }

    // Fall back to browser language
    return navigator.language ?? DEFAULT_LANGUAGE;
  }

  // Default language for SSR
  return DEFAULT_LANGUAGE;
}

This approach checks localStorage first (user preference), then falls back to the browser’s language (navigator.language), and finally defaults to the app’s default language.

Switch languages at runtime while automatically loading translation resources on-demand.

public async switchLanguage(
  language: string
): Promise<void> {
  // In browser, check if we need to load the translation first
  if (isPlatformBrowser(this.platformId)) {
    const i18next = await import('i18next');

    await Promise.all(
      NAMESPACES.map(async (namespace) => {
        const currentResources = i18next.default.getResourceBundle(
          lang,
          namespace,
        );
        // Check if any namespace is missing for this language
        if (!currentResources) {
          // Translation not loaded yet, load it dynamically
          const translationModule = await this.loadJson(lang, namespace);
          i18next.default.addResourceBundle(
            lang,
            namespace,
            translationModule.default,
          );
        }
      }),
    );
  }

  // Switch to the new language
  await changeLanguage(lang);

  // Save preference to localStorage
  if (isPlatformBrowser(this.platformId)) {
    localStorage.setItem('language', lang);
  }
}

When using dynamic imports, translations are loaded on-demand. The changeLanguage() method checks if resources are already loaded using getResourceBundle(). If missing, it dynamically imports and adds them using addResourceBundle(). This prevents redundant network requests while ensuring all needed translations are available.

Key Implementation Details:

Check localStorage first to restore user’s preferred language.
Use navigator.language as fallback for browser’s language preference.
Load missing resources dynamically with addResourceBundle().

Automate Translation with AI

Managing translations manually across multiple languages is time-consuming and error-prone. That’s where AI-powered localization comes in.

Why l10n.dev?

l10n.dev is an AI-powered translation service specifically designed for i18next JSON files:

Preserves JSON structure, keys, and nested objects.
Maintains placeholders like {{name}}, {{count}} correctly.
Automatically generates plural forms for all languages.
Handles context and interpolation intelligently.
Supports all i18next features including namespaces.

Simple Workflow

Use l10n integrations. The ai-l10n npm package brings AI-powered translation directly into your development workflow with intelligent automation features (SDK, CLI, Github Actions).

Save hours of manual translation work and avoid common errors like broken placeholders or incorrect plural forms.

Thanks for reading!

i18n Testing — A Practical Guide for QA Engineers

Anton Antonov — Tue, 09 Dec 2025 11:24:29 +0000

Building a global-ready app starts with internationalization (i18n) — but testing ensures it stays that way across languages. Let’s walk through why thoughtful i18n testing matters and how to make it effective.

Developers often focus on building features and adding i18n. But QA engineers play a critical role in ensuring a product works flawlessly for users across the globe.

In my previous article on i18n vs l10n, I explained why proper internationalization matters and how AI can help with localization. In this one, we’ll go deeper into what QA should focus on. In the examples below, I use i18next because it’s one of the most popular and feature-rich localization frameworks for JavaScript, making it easy to demonstrate concepts like pluralization and interpolation. Even if your project uses a different format (not JSON), you should still ensure it supports at least plural forms and interpolation — these are essential for providing robust internationalization capabilities. Here’s your checklist to guarantee quality:

1. All User-Facing Strings Are Extracted for Translation

Switch the app to a test locale (e.g., pseudo-language) and verify that all user-visible text appears translated, with no hard-coded or untranslated strings left.

2. Plural Form Coverage

Check that all required plural keys (_one, _few, _many, _other) are present — particularly for complex-plural languages like Polish, Russian, or Arabic.

In my previous article, I noted that developers often define only _one and _other for English, and localization teams may not add the rest. With l10n.dev, extra forms are auto-added during i18next file translation, ensuring full support for target languages.

3. Placeholder Protection (interpolation)

Confirm that dynamic placeholders ({{name}}, {{count}}, etc.) remain untouched during translation to avoid runtime issues.

l10n.dev preserves placeholders and understands their meaning for safer translations.

4. Date, Number & Currency Formats

Ensure locale-aware formatting: e.g., 1,234.56 (US) vs 1.234,56 (Germany), 24-hour vs 12-hour clock, different first days of the week.
Check currencies are correct for the target market — they should not be changed during translation.
Verify date/time accuracy across all relevant time zones.

As highlighted earlier, l10n.dev intelligently converts formats — for example, turning “Founded on July 4, 1776” into “1776年7月4日創設” for Japanese locale.

5. Text Length & UI Layout

Some languages (like German or Russian) tend to be 30–40% longer than English. Your UI should adapt without truncation. Simulate long strings and ensure buttons, labels, and menus resize gracefully.
Languages like Arabic and Hebrew are read right-to-left (RTL). Verify that text alignment, icons, and navigation reverse correctly.

If a translation is longer than the source, AI i18n translator can intelligently shorten it without losing context. Example: “administrator” → “admin” in space-limited UI components.

6. Missing Keys & Fallbacks

Run localized build and click through screens to confirm no fallback keys (like auth.login.title) appear accidentally.

l10n.dev preserves translation files structure and key ordering for cleaner diffs and easier review.

7. Contextual Variants

Ensure that gender (e.g., _male, _female), tone (formal/informal), or role-based translations are properly used. Keys like greeting_formal vs greeting_informal should render correctly based on context.

8. Encoding and Character Support

App should handle all Unicode characters — including emojis, right-to-left scripts, and accented letters.

Automating i18n Testing with Pseudo-Localization

Pseudo-localization is the process of transforming your app’s source text into an altered, fake “language” to mimic how UI behaves after translation. Automation QA teams can use this to detect i18n issues before the real translation arrives.

Why It’s Useful

Exposes layout breakages caused by text expansion.
Surfaces encoding issues by adding accented characters.
Ensures all strings are translatable (no hard-coded text).
Reveals placeholder mishandling.
Helps define translation length limits (e.g., maximum allowed characters).

Automation Strategies for QA

1. Accented & Non-Latin Characters

What to do: Replace Latin letters with accented forms or different scripts. Example: “Save” → “Šàvē”
QA check: Ensure all characters display correctly and nothing breaks due to encoding.

2. Text Expansion Simulation

What to do: Automatically expand each string by ~30–40% to mimic long languages like German or Finnish. Wrap with markers for easy clipping detection. Example: “Save” → [★ Šàvēēēēē ★]
QA check: Use automated screenshot comparison to spot UI overflow, clipping, or misalignment.

3. Placeholder Stress Testing

What to do: Replace interpolation variables (placeholders) with visible markers (e.g., , ). Example: “You have {{count}} items” → “You have items”
QA check: Run regression tests; fail if a marker is missing, or escaped (<COUNT>).

4. RTL Simulation

What to do: Wrap text in right-to-left (RTL) markers \u202E${text}\u202C to simulate Arabic or Hebrew.
QA check: Verify alignment, text direction, and mirroring are correct.

5. CI/CD Integration

What to do: Add pseudo-localization to your automated test pipeline.
QA check: Block deployment if tests detect missing translations, broken placeholders, or layout issues.

Below the screenshot is a pseudo-localization example used to identify potential internationalization (i18n) issues. The font and size are identical on both sides, but supporting other scripts often requires more space:

To automate pseudo-localization, check out pseudo-l10n — an npm package that generates pseudo-localized JSON files with configurable text expansion, accented characters, visual markers, and RTL support. Install with npm install -g pseudo-l10n and run pseudo-l10n en.json pseudo.json to instantly create test locales.

By automating i18n testing, you ensure that localization becomes smooth, fast, and cost-effective. With AI localization, l10n.dev can help you get there.

Thanks for reading!

i18n vs l10n: Why Developers Should Care — and How AI Can Help

Anton Antonov — Thu, 04 Dec 2025 10:57:44 +0000

Internationalization (i18n) and localization (l10n) often feel like “later” problems — right up until they’re not.

As developers, we’ve all done something like this:

<button>Order now</button>

Or buried inside a template:

<p>Welcome back, {{ user.name }}!</p>

It works fine — until your product team says,
“We’re launching in Japan, Germany, and the Middle East next quarter.”

Suddenly, every hardcoded string turns into technical debt. Engineers scramble to extract text, designers fight broken layouts, QA chases missing translations, and releases slip.

That’s the moment you stop and ask: So, what’s i18n vs l10n — and why is it critical?

In short:

Internationalization (i18n) is how you prepare your app to support multiple languages.
Localization (l10n) is how you adapt your app to each language and culture.

Understanding the difference is key to building global-ready products — so let’s break it down with real examples and developer-friendly guidance.

Hi! I’m a developer with deep experience in building scalable applications, including time in the game development industry at companies like Plarium, known for MMO RPG titles where localization is critical. Every project I worked on — from games to enterprise apps — had to support internationalization (i18n) and localization (l10n) from the ground up.

Now, I’m using that experience to improve how apps are localized. I’m building an AI-powered service that enhances localization pipelines, and I’ve seen firsthand how getting i18n and l10n right can accelerate global growth — or become a blocker.

In this post, we’ll explore:

The difference between i18n and l10n (with real examples)
Best practices to future-proof your codebase
How AI can automate and streamline localization at scale

What is i18n? (Internationalization)

Internationalization is the process of designing and building your software so it can support multiple languages, regions, and cultural formats without needing code changes later.

Think of it as laying the groundwork that makes your app ready for any language — the logic, structure, and flexibility needed to support global users.

1. Extract All User-Facing Strings

Hardcoded strings are your biggest enemy when preparing an app for localization. They hide in your templates and components, making translation painful and error-prone. That’s why the first step in proper internationalization is extracting all user-facing text into structured files — most commonly JSON.

JSON has become the de facto format for localization in web development, especially with JavaScript-based frameworks like React, Angular, and Vue. It’s simple, lightweight, easy to version in Git, and works well with popular i18n libraries.

But more importantly, JSON supports nested keys, allowing you to organize translations in a way that mirrors your application’s structure.

{
  "auth": {
    "login": {
      "title": "Sign in to your account",
      "submit": "Log in",
      "forgot": "Forgot your password?",
      "errors": {
        "required": "This field is required",
        "invalid": "Invalid email or password"
      }
    }
  }
}

🧑‍💻 In Code (React + i18next):

import { useTranslation } from 'react-i18next';

const LoginForm = () => {
  const { t } = useTranslation();

  return (
    <form>
      <h1>{t('auth.login.title')}</h1>
      <input placeholder={t('auth.login.forgot')} />
      <button>{t('auth.login.submit')}</button>
    </form>
  );
};

This way, your components remain language-agnostic — and localization becomes a plug-and-play process.

You can use tools like i18next-parser (for React/Vue) or ngx-translate-extract (for Angular) to automatically extract strings.

Why i18next?

Among many i18n libraries, i18next stands out as the most widely adopted in the JavaScript ecosystem — for good reason:

Works seamlessly with React, Vue, Angular, Next.js, and others
Supports namespaces, lazy loading, pluralization, context, and interpolation
Built-in support for JSON format with nested keys
Actively maintained with a large community and ecosystem (e.g., react-i18next, i18next-parser, i18next-browser-languagedetector)
Compatible with AI-powered translation workflows and external services (like l10n.dev 😉)

In contrast, formats like .po, .xliff, or .properties are more common in older or enterprise environments and may require additional tooling or conversion layers.

2. Use Meaningful Keys — Not Sentences or Raw IDs

When defining your translation keys, avoid using full text strings or generic IDs. Instead, use descriptive, meaningful keys that reflect the context and structure of your application.

✅ Good:

"form.error.required": "This field is required"

🚫 Bad:

"This field is required": "Ce champ est requis"

🚫 Also Bad:

"msg_001": "This field is required"

Why it matters:

Reusable: A key like form.error.required can be used across multiple forms without duplication.
Maintainable: If the English text changes, the key stays the same — so translations don’t need to be redone.
Clear: Developers and translators can quickly understand the purpose of the key from its name.
Stable: Avoids unnecessary changes in translation files and version control noise.

Use dot notation to reflect app structure (form.login.button) and avoid long, flat key files.

3. Split into Namespaces — Avoid One Giant JSON File

As your app grows, so do your translations. Splitting them into namespaces (e.g., auth.json, dashboard.json, common.json) improves:

Maintainability
Load time (you can lazy-load only needed namespaces)
Collaboration (teams can own parts of the translation structure)

// locales/en/auth.json
{
  "login.title": "Sign in to your account"
}

i18next.use(initReactI18next).init({
  ns: ['auth', 'common'],
  defaultNS: 'common',
});

What Is Localization (l10n)?

Localization isn’t just about translating words — it’s about adapting your entire user interface to feel native in another language and culture. That includes grammar, plural rules, date formats, name conventions, and even tone.

So why do the next practicies matter?

Because if developers don’t structure things properly — like using plural forms, contexts, or interpolation — translators can’t do their job well. The result? Awkward translations, broken layouts, or content that simply doesn’t make sense to your users.

Even the best AI translator or localization team can’t fix a poor foundation. You need to give them the right keys, metadata, and flexibility — and that’s your job during i18n.

4. Interpolation — Insert Dynamic Values into Translations

Interpolation lets you inject dynamic data (like user names, numbers, and dates) into your translated strings without hardcoding them. This keeps translations reusable, secure, and easier to maintain.

✅ Good Example:

{
  "welcome": "Welcome, {{name}}!",
  "order_summary": "Total: {{amount}} {{currency}}"
}

In your React code:

t('welcome', { name: 'Anton' })        // → Welcome, Anton!
t('order_summary', { amount: 25, currency: 'USD'})     // → Total: 25 USD

🔐 i18next escapes all values by default to protect against XSS. You can disable it if needed with:

{ interpolation: { escapeValue: false } }

🚫 What Should Not Be Translated

When preparing your app for localization, it’s just as important to know what not to include in your translatable strings:

❌ Dates and times should not be translated manually — instead, format them to user’s locale at runtime.
❌ Dynamic data like numbers, prices, and currencies should use interpolation. Translators should never rewrite actual values like 25 USD.
❌ Proper names (e.g. names, brands, company names) should stay intact.
✅ Only historical or well-known proper names (e.g., “Christopher Columbus”) may be translated. Converting the name from one script to another, for example: Steve Jobs -> Cтив Джобс

How l10n.dev Handles This

l10n.dev translates i18n JSON files with AI that understands context — it intelligently preserves placeholders like {{name}}, {{count}}, and {{amount}}, and avoids awkward or literal translations that are common with basic machine translation.

Understands placeholder meaning and keeps dynamic data intact.
Automatically converts date and number formats to match the target locale — especially useful when translating historical or factual content like “Founded on July 4, 1776” → “Основан 4 июля 1776 г.”.
Knows what not to translate, like user names, currencies, and runtime values, reducing risk and saving time.
Ensures translations feel natural and localized, not robotic or confusing.

This makes l10n.dev a smarter choice for developers — giving you production-ready translations that respect both your code and your users.

5. Handle Plural Forms Properly

Different languages treat plurals differently. English is simple:

{
  "days_count_one": "{{count}} day",
  "days_count_other": "{{count}} days"
}

But Slavic languages like Russian, Polish, and Ukrainian require 3 forms:

one → 1 день
few → 2 дня, 3 дня, 4 дня
other → 0 дней, 5 дней, 11 дней, etc.

✅ No need to worry — i18next handles these rules for you. You just define the forms in your translation files, and i18next picks the right one based on the current language and count value.

Example:

{ 
  "days_count_one": "{{count}} день",
  "days_count_few": "{{count}} дня",
  "days_count_other": "{{count}} дней"
}

And in code:

t('days_count', { count: 3 })

That’s it — i18next figures out the rest

Of course, developers aren’t translators — so it’s perfectly normal to have only _one and _other for English. But when your app is translated into languages with complex plural rules, the localization team should expand those keys as needed (e.g., add _few, _many, etc.).

In theory, the localization team should handle this.
But in reality, many translators are native speakers with no knowledge of i18next or plural formatting logic. If they see two keys in the source, they’ll likely return just two — even when the target language requires more.

This creates bugs or incorrect grammar in your app.

✅ That’s why l10n.dev, an AI-powered i18n translation service, automatically adds all required plural forms for the target language during translation. So even if your source file is minimal, the translated result is fully structured — and your app works correctly in every locale, with no guesswork or missing forms.

6. Context — Handling gender, tone, or grammatical cases

Context is used when a translation changes based on a situation — like gender, formal/informal speech, or other grammatical variations.

Example: Gender-based context

{
  "user_info": "User info",
  "user_info_male": "His info",
  "user_info_female": "Her info"
}

In code:

t('user_info', { context: 'male' })   // → His info
t('user_info', { context: 'female' }) // → Her info

This works by appending _contextValue to the base key. i18next will automatically resolve the correct variant.

Common use cases for context:

Gender (he/she/they)
Formal vs informal (_formal, _informal)
Language-specific word forms (e.g., in Slavic languages)
Role-based phrasing (admin vs user)

You can combine both

{
  "greeting": "Hello, {{name}}!",
  "greeting_formal": "Good day, {{name}}!"
}

t('greeting', { name: 'Anton', context: 'formal' })
// → Good day, Anton!

Why This Matters

Interpolation keeps your UI dynamic and localized
Context handles linguistic nuances correctly
Both help translators deliver accurate, natural-sounding results — without complex logic in your code

And yes — i18next handles all the fallback logic for you, so you don’t have to worry if a context variant is missing.

How AI Makes It Easier

AI-powered localization service like l10n.dev take the complexity out of localization by:

Translating with context awareness, not just word-for-word.
Preserving placeholders and interpolations ({{count}}, {{name}}, etc.) so translations remain functional.
Automatically adjusting date/number formats to the target locale.
Ensuring proper pluralization, even for complex languages like Russian, Polish, or Arabic.
Respecting original key ordering in files for cleaner diffs and easier reviews.
Letting you translate only new strings, so you don’t retranslate your whole app every time.
Keeping html, tabs, line breaks in translated text.

All you need to do is follow best practices for i18n — and let AI handle the rest.

Thanks for reading!