Angular i18n CLI

By Softwarity

A CLI tool to help manage Angular i18n configuration in your projects. This tool is designed to work in conjunction with Angular's built-in i18n mechanism, providing a simplified way to manage your internationalization configuration.

Related Services

• Softwarity.io - API Gateway based on Spring Gateway
• XLIFF AI Translator - AI-powered translation tool for Angular applications

Requirements

• Angular 19 or higher
• Node.js 18 or higher

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, you need to install the required dependencies:

# Install @angular/localize
# See: https://angular.dev/guide/i18n
ng add @angular/localize

# Install ng-extract-i18n-merge
# See: https://github.com/daniel-sc/ng-extract-i18n-merge#readme
ng add ng-extract-i18n-merge

Integration with Angular i18n

This CLI tool is specifically designed to work with Angular's built-in i18n mechanism. It helps you:

• Configure the i18n settings in your angular.json
• Manage locale configurations
• Set up the correct format for XLF files
• Configure the build process for multiple locales

The tool assumes you are using Angular's standard i18n workflow with XLF files and the @angular/localize package.

Commands

Initialize i18n configuration (init)

Initializes the i18n configuration in your Angular project.

angular-i18n init

Project Selection

• If your workspace has only one project, it will be automatically selected
• If your workspace has multiple projects, you'll be prompted to select one

What it modifies in angular.json

1. Adds i18n configuration:

{
  "projects": {
    "your-project": {
      "i18n": {
        "sourceLocale": {
          "code": "en",
          "subPath": "en"
        },
        "locales": {}
      }
    }
  }
}

2. Adds build configuration for the source locale:

{
  "projects": {
    "your-project": {
      "architect": {
        "build": {
          "configurations": {
            "en": {
              "localize": ["en"],
              "deleteOutputPath": false
            }
          }
        }
      }
    }
  }
}

3. Configures extract-i18n format:

{
  "projects": {
    "your-project": {
      "architect": {
        "extract-i18n": {
          "options": {
            "format": "xlf"
          }
        }
      }
    }
  }
}

Add a new locale (add)

Adds a new locale to your project.

angular-i18n add

Project Selection

• If your workspace has only one project, it will be automatically selected
• If your workspace has multiple projects, you'll be prompted to select one

Locale Input

• You'll be prompted to enter a locale code (e.g., 'fr', 'es', 'de')
• The code will be validated using the Intl API

What it modifies in angular.json

1. Adds the locale to i18n configuration:

{
  "projects": {
    "your-project": {
      "i18n": {
        "locales": {
          "fr": {
            "translation": "src/locale/messages.fr.xlf",
            "subPath": "fr"
          }
        }
      }
    }
  }
}

2. Adds build configuration for the new locale:

{
  "projects": {
    "your-project": {
      "architect": {
        "build": {
          "configurations": {
            "fr": {
              "localize": ["fr"],
              "deleteOutputPath": false
            }
          }
        }
      }
    }
  }
}

3. Adds the locale file to extract-i18n target files:

{
  "projects": {
    "your-project": {
      "architect": {
        "extract-i18n": {
          "options": {
            "targetFiles": ["messages.fr.xlf"]
          }
        }
      }
    }
  }
}

Remove a locale (remove)

Removes a locale from your project.

angular-i18n remove

Project Selection

• If your workspace has only one project, it will be automatically selected
• If your workspace has multiple projects, you'll be prompted to select one

Locale Selection

• You'll be prompted to select a locale from the list of configured locales

What it modifies in angular.json

1. Removes the locale from i18n configuration
2. Removes the build configuration for the locale
3. Removes the locale file from extract-i18n target files

Error Handling

The CLI includes several error checks:

• Verifies that @angular/localize is installed
• Verifies that ng-extract-i18n-merge is installed
• Validates locale codes using the Intl API
• Ensures i18n is initialized before adding or removing locales
• Ensures extract-i18n is configured before adding locales