Common Features / Globalization / Localization / Translation of Messages / 
New to Kendo UI for Angular? Start a free 30-day trial

Translation of Messages

You can translate the components into different languages by obtaining localized messages.

The localized messages can be used both individually and jointly between the available sources:

  • Message attributes take precedence over other sources.
  • Message files take precedence over the message service.

Using the Angular i18n Framework

Angular delivers a dedicated toolkit for localizing application messages. For more information on how to use the framework, refer to the Internationalization (i18n) guide.

Components, coming from external libraries are not translated in Angular 17 app, run with ng-serve. You can find more details in the troubleshooting section.

Overview of the Sample Project

This sample project uses the Angular CLI 9.x to help manage the i18n tasks.

For more information, refer to the Angular Internationalization documentation. For the complete sample application, refer to the github.com/telerik/kendo-angular-i18n-sample GitHub repository.

To utilize the Angular localization approach in the sample application:

  1. Set up the project
  2. Add the texts for localization
  3. Add a Kendo UI component for Angular
  4. Extract the application messages for localization
  5. Translate the messages into Spanish
  6. Populate the translations in the application
  7. Run the application for the target locale

Setting Up the Project

Use the Angular CLI and add the Kendo UI styles as described in the article on getting started.

ng new --defaults kendo-i18n-sample
cd kendo-i18n-sample

Adding the Texts for Localization

Add the localizable messages to the src/app/app.component.html template. The i18n attribute accepts optional meaning and description that are separated by a pipe (|) symbol. They are embedded in the message file and provide context for the translator.

<h1 i18n="User welcome|An introduction header for this sample">Hello, World!</h1>

Adding the Grid Component

  1. Add the Grid package to the application.

    ng add @progress/kendo-angular-grid

  2. Add an empty Grid to the src/app/app.component.html template. Though the component is empty, you will be able to see its No Records available message.

    <kendo-grid></kendo-grid>

  3. Start the application to confirm that the settings that are applied so far function properly. To access the application, use the localhost:4200 port.

    ng serve

Extracting the Messages

The next step is to create a translation source file containing all messages from the application and libraries, such as Kendo UI for Angular.

To create the translation source file run:

ng extract-i18n --output-path src/locale

As a result, the src/locale/messages.xlf file now includes the Hello, World! and the built-in Grid messages. The machine-readable "meaning" note is a unique key that is used to locate the string in the message pack.

  <trans-unit id="..." datatype="html">
    <source>Hello, World!</source>
    <context-group purpose="location">
      <context context-type="sourcefile">app/app.component.ts</context>
      <context context-type="linenumber">1</context>
    </context-group>
    <note priority="1" from="description">An introduction header for this sample</note>
    <note priority="1" from="meaning">User welcome</note>
  </trans-unit>
  <trans-unit id="..." datatype="html">
    <source>No records available.</source>
    <context-group purpose="location">
      <context context-type="sourcefile">../node_modules/@progress/kendo-angular-grid/dist/es/grid.component.d.ts</context>
      <context context-type="linenumber">7</context>
    </context-group>
    <note priority="1" from="description">The label visible in the Grid when there are no records</note>
    <note priority="1" from="meaning">kendo.grid.noRecords</note>
  </trans-unit>
  ...

See Create a translation source file from the Angular guide for more details about the xi18n command.

Translating the Messages

The sample project uses Spanish as a target language for translation.

  1. Copy the src/locale/messages.xlf file to src/locale/messages.es.xlf.

  2. Change the locale in the file to "es".

    <file source-language="es" datatype="plaintext" original="ng2.template">

  3. Add a <target> tag right after <source> and type in the translation for the Hello, World! message in it.

    <trans-unit id="..." datatype="html">
  <source>Hello, World!</source>
  <target>¡Hola Mundo!</target>
  <context-group purpose="location">
    <context context-type="sourcefile">app/app.component.ts</context>
    <context context-type="linenumber">1</context>
  </context-group>
  <note priority="1" from="description">An introduction header for this sample</note>
  <note priority="1" from="meaning">User welcome</note>
</trans-unit>

  4. (Optional) Add the translations of the Kendo UI messages. You can skip this step if the translations for your locale are shipped by Kendo UI for Angular as part of the message pack.

Populating the Translations

To add the translations of the Grid messages in Spanish, populate them from the message pack.

  1. Install the @progress/kendo-angular-messages package.

    npm install --save @progress/kendo-angular-messages

  2. Populate the message file from the message pack. Note that the example uses the full "es-ES" locale ID.

    npx kendo-translate src/locale/messages.es.xlf --locale es-ES

    As a result, the console output now includes the number of translated messages.

    Done.
  86 targets translated.
  0 non-empty targets skipped. Use --force to overwrite.

  3. (Optional) Override existing translations.

    Add the --force tag to allow the kendo-translate utility to overwrite existing <target> elements.

Configuring the Application

To add the new locale to the application, create a "i18n" section to the project settings in angular.json:

{
  ...
  "projects": {
    "kendo-i18n-sample": {
      ...
      "i18n": {
        "sourceLocale": "en-US",
        "locales": {
          "es": "src/locale/messages.es.xlf"
        }
      }
    }
  }

Then, add two configuration profiles both to the "build" and to the "serve" sections:

  • "es"—A new profile with localization enabled.
  • "production-es"—A copy of the existing "production" profile with the added localization.
{
  "projects": {
    "kendo-i18n-sample": {
      "architect": {
        "build": {
          "configurations": {
            ...
            "es": {
              "localize": ["es"]
            },
            "production-es": {
              "localize": ["es"],
              "fileReplacements": [
                {
                  "replace": "src/environments/environment.ts",
                  "with": "src/environments/environment.prod.ts"
                }
              ],
              "optimization": true,
              "outputHashing": "all",
              "sourceMap": false,
              "extractCss": true,
              "namedChunks": false,
              "extractLicenses": true,
              "vendorChunk": false,
              "buildOptimizer": true,
              "budgets": [
                {
                  "type": "initial",
                  "maximumWarning": "2mb",
                  "maximumError": "5mb"
                },
                {
                  "type": "anyComponentStyle",
                  "maximumWarning": "6kb",
                  "maximumError": "10kb"
                }
              ]
            }
          }
        },
        "serve": {
          "configurations": {
            ...
            "es": {
              "browserTarget": "kendo-i18n-sample:build:es"
            },
            "production-es": {
              "browserTarget": "kendo-i18n-sample:build:production-es"
            }
          }
        }
    ...
}

To start the application in the Spanish locale, run:

ng serve --configuration=es

Using the Message Service

You can provide translated messages by using a custom service. To achieve this through the Angular i18n framework, you need to set up the application in a very specific way. As a simpler alternative, you can inject a message service that provides localized messages.

The get method of the service will be called for each message identified by its unique key. For the full list of available keys, refer to the kendo-angular-messages GitHub repository.

The message files are listed in a hierarchical .yaml format. To create the key, prepend the parent keys. For example, the following message will be requested as "kendo.grid.noRecords".

kendo:
  grid:
    # The label visible in the Grid when there are no records
    noRecords: No records available.

If for a given key the service returns undefined, the default translation will be used.

Implementing the Custom Service

  1. Extend the MessageService abstract base class. It defines a single get method returns the localized message from the provided hierarchical key.

    If the get method returns undefined, the message will be looked up from the message attributes or the Angular i18n message files, if available.

  2. Provide the implementation in the application root module or in a child component.

Example
View Source
Change Theme:

Updating Messages Dynamically

In specific scenarios—for example, if the application language changes dynamically or if the messages are loaded asynchronously—you can change the translations of individual or all messages that are provided by the message service at runtime. To update the messages, call the notify method of the base message service. The notify method also accepts an optional parameter which enables the simultaneous change of the text direction from right-to-left to left-to-right and vice versa.

Example
View Source
Change Theme:

Using the Message Attributes

You can override individual messages by utilizing the attribute bindings.

In i18n applications, attributes take precedence over messages.

Example
View Source
Change Theme:

The attributes are localizable in the context of your application. You can provide different descriptions and meanings to them on a per-instance basis.

<kendo-grid>
    <kendo-grid-messages i18n-noRecords="No records template for the products Grid" noRecords="No records found">
    </kendo-grid-messages>
</kendo-grid>

Suggested Links

Previous
Getting Started
Next
RTL Support

In this article

Not finding the help you need?

Contact Support