All Components

Translation of Messages

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

The localized messages can be used both individually or in a combination 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 toolset for localizing application messages. For more information on how to use the framework, refer to the Internationalization (i18n) Cookbook article.

The following sample project uses the Angular CLI to help manage the i18n tasks. For more information, refer to the article on Angular CLI Internationalization. For the complete sample application, refer to github.com/telerik/kendo-angular-i18n-sample.

To utilize the Angular localization approach in the sample application:

1. Set up the project
1. Add the texts for localization
1. Add a Kendo UI component for Angular
1. Extract the application messages for localization
1. Translate the messages into Spanish
1. Populate the translations in the application
1. 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 kendo-i18n-sample --style=scss
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

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

  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

Extracting the Messages

Run the ng xi18n --output-path src/i18n command. 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>
   <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>
 ...

Translating the Messages

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

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

    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.

Initiating the Application

To start the application in the Spanish locale, run the ng serve --aot --i18n-file=src/i18n/messages.es.xlf --locale=es command.

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