All Components

Translation of Messages

You can translate the Kendo UI components for Angular into different languages.

Custom Messages by Components

Currently, the following components support the option for localizing their messages:

Message Sources

Localized messages can be provided by:

They can be used individually or in combination.

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

Message Packs

As part of the @progress/kendo-angular-messages package, Kendo UI for Angular ships ready-to-use translations for common locales. The package is hosted on GitHub and is open for contributions.

The translations are used to populate Angular Internationalization (i18n) message files.

Using the Angular i18n Framework

Angular delivers a dedicated tool-set for localizing application messages. For more information on how to use the framework, refer to the Internationalization (i18n) Cookbook article.

Currently, the Angular CLI does not include support for i18n features. For more information on the development of this feature, refer to the angular/angular#2201 issue. As a result, to set up and deploy i18n applications, you have to follow additional steps. For a practical example on the procedure, refer to Deploying an i18n Angular app with angular-cli by Philippe Martin.

This section demonstrates how to:

To access the complete sample application, refer to github.com/telerik/kendo-angular-i18n-sample.

Set Up the Application

To create a sample application:

  1. Set up a project by using the Angular CLI and add the Kendo UI styles as described in the article on getting started.

    ng new kendo-i18n-sample --style=scss
    cd kendo-i18n-sample
  2. Modify the compiler configuration in src/tsconfig.app.json by adding the angularCompilerOptions setting. As a result, the compiler gets instructed to output message files in the src/i18n folder. The exclude line is a workaround for an existing issue with the Angular Compiler.

    {
     "compilerOptions": { ... },
     "angularCompilerOptions": {
       "genDir": "i18n"
     }
    }

Add the Texts for Localization

You need to 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>

Add the Grid Component

For detailed information on adding the Kendo UI Grid to your application, refer to the section on installing the Grid.

To add the component to the sample i18n application:

  1. 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>
  2. Start the application to confirm that the settings applied so far function properly. The application is available at localhost:4200.

    ng serve --aot

Extract the Messages

To extract the application messages, run:

cd src
../node_modules/.bin/ng-xi18n

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

<trans-unit id="..." datatype="html">
  <source>hello, world!</source>
  <target/>
  <context-group purpose="location">
    <context context-type="sourcefile">src/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>
  <target/>
  <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>
...

Translate the Messages

This scenario uses Spanish as a target language for translation.

To translate the Grid messages into Spanish:

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

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

    <file source-language="es" datatype="plaintext" original="ng2.template">
  3. Type in the translation for the Hello, World! message between the <target> elements.

    <trans-unit id="..." datatype="html">
     <source>hello, world!</source>
     <target>¡Hola Mundo!</target>
     <context-group purpose="location">
       <context context-type="sourcefile">src/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.

Populate 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.

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

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

    Done.
     10 targets translated.
     0 non-empty targets skipped. Use --force to overwrite.
  3. (Optional) Override the individual translations.

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

Initiate the Application

To start the application in the Spanish locale, run:

ng serve --aot --i18n-file=src/i18n/messages.es.xlf --locale=es

The application will not start unless all messages are translated.

Using the Message Service

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

To implement the 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.

import { MessageService } from '@progress/kendo-angular-l10n';

const messages = {
  'kendo.grid.noRecords': 'No hay datos disponibles.'
};

export class MyMessageService extends MessageService {
  public get(key: string): string {
    return messages[key];
  }
}
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { HttpModule } from '@angular/http';
import { GridModule } from '@progress/kendo-angular-grid';
import { MessageService } from '@progress/kendo-angular-l10n';

import { MyMessageService } from './my-message.service';
import { AppComponent } from './app.component';

@NgModule({
  imports:      [ BrowserModule, HttpModule, GridModule ],

  // Provide our message service for the whole application
  providers:    [{ provide: MessageService, useClass: MyMessageService }],
  declarations: [ AppComponent ],
  bootstrap:    [ AppComponent ]
})

export class AppModule { }
import { Component } from '@angular/core';

@Component({
  selector: 'my-app',
  template: `
      <kendo-grid [data]="[]">
      </kendo-grid>
    `
})
export class AppComponent {}
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

import { AppModule } from './app.module';

const platform = platformBrowserDynamic();
platform.bootstrapModule(AppModule);

Using the Message Attributes

You can override individual messages by utilizing the attribute bindings.

In i18n applications, attributes take precedence over messages.

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

@Component({
  selector: 'my-app',
  template: `
    <kendo-grid>
        <kendo-grid-messages noRecords="No hay datos disponibles.">
        </kendo-grid-messages>
    </kendo-grid>
    `
})
export class AppComponent {}
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { HttpModule } from '@angular/http';
import { GridModule } from '@progress/kendo-angular-grid';

import { AppComponent } from './app.component';

@NgModule({
  imports:      [ BrowserModule, HttpModule, GridModule ],
  declarations: [ AppComponent ],
  bootstrap:    [ AppComponent ]
})

export class AppModule { }
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

import { AppModule } from './app.module';

const platform = platformBrowserDynamic();
platform.bootstrapModule(AppModule);

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>
In this article