@softwarity/angular-i18n-cli

A CLI tool to simplify Angular i18n configuration management. Automates the setup and management of internationalization settings in angular.json for Angular 19+ projects using XLF files and @angular/localize.

Getting Started

Requirements

Angular 19 or higher
Node.js 18 or higher
@angular/localize installed
ng-extract-i18n-merge installed

Installation

# Install globally
$ npm install -g @softwarity/angular-i18n-cli

# Or install in your project
$ npm install --save-dev @softwarity/angular-i18n-cli

Prerequisites

Before using the CLI, install the required Angular dependencies:

$ ng add @angular/localize
$ ng add ng-extract-i18n-merge

Commands

play_arrow angular-i18n init

Initializes the i18n configuration in your Angular project. Sets up the source locale, build configurations, and extract-i18n format.

Usage

$ angular-i18n init
? Enter source locale code (default: en): en
i18n configuration initialized successfully!

Usage

$ angular-i18n init --source-locale en

# With explicit project (for monorepos)
$ angular-i18n init --source-locale en --project my-app

Options

Option	Description	Default
`--source-locale <code>`	Source locale code (BCP 47)	`en`
`--project <name>`	Project name (for monorepo workspaces)	Auto-selected if single project

What it modifies in angular.json

{
  "projects": {
    "your-project": {
      "i18n": {
        "sourceLocale": { "code": "en", "subPath": "en" },
        "locales": {}
      },
      "architect": {
        "build": {
          "configurations": {
            "en": { "localize": ["en"], "deleteOutputPath": false }
          }
        },
        "extract-i18n": {
          "options": { "format": "xlf" }
        }
      }
    }
  }
}

add_circle angular-i18n add

Adds a new locale to your project. Validates the locale code using the Intl.DisplayNames API (BCP 47 compliance).

Usage

$ angular-i18n add
? Enter locale code (BCP 47) (e.g., fr): fr
Locale fr added successfully!

Usage

$ angular-i18n add --locale fr
Locale fr added successfully!

# Add multiple locales
$ angular-i18n add --locale de
$ angular-i18n add --locale es

Options

Option	Description	Default
`--locale <code>`	Locale code to add (BCP 47, e.g. `fr`, `de`, `es`)	-
`--project <name>`	Project name (for monorepo workspaces)	Auto-selected if single project

What it modifies in angular.json

{
  "i18n": {
    "locales": {
      "fr": {
        "translation": "src/locales/messages.fr.xlf",
        "subPath": "fr"
      }
    }
  },
  "architect": {
    "build": {
      "configurations": {
        "fr": { "localize": ["fr"], "deleteOutputPath": false }
      }
    },
    "extract-i18n": {
      "options": {
        "targetFiles": ["messages.fr.xlf"]
      }
    }
  }
}

remove_circle angular-i18n remove

Removes a locale from your project. Cleans up the i18n config, build configuration, and extract-i18n target files.

Usage

$ angular-i18n remove
? Select locale to remove:
  fr
  de
  > es
Locale es removed successfully!

Usage

$ angular-i18n remove --locale fr
Locale fr removed successfully!

Options

Option	Description	Default
`--locale <code>`	Locale code to remove	-
`--project <name>`	Project name (for monorepo workspaces)	Auto-selected if single project

Typical Workflow

Install prerequisites

$ ng add @angular/localize
$ ng add ng-extract-i18n-merge

Initialize i18n

$ angular-i18n init
? Enter source locale code (default: en): en
i18n configuration initialized successfully!

$ angular-i18n init --source-locale en
i18n configuration initialized successfully!

Add target locales

$ angular-i18n add
? Enter locale code (BCP 47) (e.g., fr): fr
Locale fr added successfully!

$ angular-i18n add
? Enter locale code (BCP 47) (e.g., fr): de
Locale de added successfully!

$ angular-i18n add --locale fr
Locale fr added successfully!

$ angular-i18n add --locale de
Locale de added successfully!

Extract & translate

$ ng extract-i18n
# Translation files are generated in src/locales/
# Translate messages.fr.xlf, messages.de.xlf, etc.

Build for a specific locale

$ ng build --configuration fr

Error Handling

The CLI performs validation checks and provides clear error messages:

# Missing @angular/localize
$ angular-i18n init
@angular/localize is not configured.
Please run the following commands:
  ng add @angular/localize
  ng add ng-extract-i18n-merge

# Invalid locale code
$ angular-i18n add --locale xyz
Error: Please enter a valid locale code. xyz is not a valid BCP 47 tag.

# i18n not initialized
$ angular-i18n add --locale fr
Error: i18n not initialized. Run init-i18n first.

Related Services

Softwarity.io

API Gateway based on Spring Gateway

XLIFF AI Translator

AI-powered translation tool for Angular applications

Features

Angular 19+ support - Designed for the latest Angular i18n workflow
Interactive & non-interactive modes - Use interactively or automate via scripts
Locale validation - BCP 47 compliance via Intl.DisplayNames API
Monorepo support - Works with multi-project Angular workspaces
Safe configuration - Validates prerequisites before modifying angular.json
XLF format - Standard XLIFF translation file format