Label Module Provider

Want to localize labels and reuse them across different pages? The Label Module Provider serves file-based labels as ES modules, and it shows different translations of each label depending on the user's locale.

To determine the user's locale, the Label Module Provider evaluates these resources in this order:

1. The locale path parameter in the request
2. The Accept-Language header in the request
3. The default locale set by the runtime

Create Reusable Labels

In your project's src directory, add a labels folder. For each supported locale, create a JSON file that contains all the labels you want to use. The name of each file should be the all-lowercase locale code corresponding to the language and region of its labels. For example, if you have labels for the fr-FR locale, put them in a file named fr-fr.json.

If the Label Module Provider can't find a label file for a requested language and region code, it looks for a file that corresponds to only the requested language. For example, if a user requests en-US labels but you don't have an en-us.json file, the module provider looks for an en.json file as a fallback.

src/
  ├── assets/
  ├── labels/
  │   ├── en.json       // English
  │   ├── es.json       // Spanish
  │   ├── it.json       // Italian
  │   └── fr-fr.json    // French (France)
  ├── labelHandler.ts   // route handler for template translations
  ├── layout.html       // static layout template
  └── modules/
lwr.config.json
package.json

Here's an example of a file with labels for the English (en) language.

{
    "title": "Translation",
    "home": {
        "greeting": "Welcome"
    },
    "animal": {
        "cat": "Cat",
        "dog": "Dog"
    }
}

The same labels for the French (fr) language and country of France (FR) are in a separate file.

{
    "title": "Traduction",
    "home": {
        "greeting": "Bienvenu"
    },
    "animal": {
        "cat": "Chat",
        "dog": "Chien"
    }
}

Add the Label Module Provider

To import the package for this module provider (@lwrjs/label-module-provider), run this code in your terminal. This also adds a dependency on @lwrjs/label-module-provider to your project's package.json.

npm install @lwrjs/label-module-provider

Then, register the module provider in lwr.config.json. Remember to include all the default module providers in the moduleProviders array.

{
  "moduleProviders": [
    "@lwrjs/label-module-provider",       // Add the Label Module Provider
    "@lwrjs/app-service/moduleProvider",  // Default provider
    "@lwrjs/router/module-provider",      // Default provider
    "@lwrjs/lwc-module-provider",         // Default provider
    "@lwrjs/npm-module-provider",         // Default provider
    "@lwrjs/module-registry/externals-module-provider"    // Default provider
  ]
}

In the same config file, add a route handler to the app route.

{
    "routes": [
        {
            "id": "labels",
            "path": "/",
            "routeHandler": "$rootDir/src/labelHandler.ts"
        }
    ]
}

Optional: Configure the Label Module Provider

In lwr.config.json, you can set a package specifier for importing labels and customize the filepath of the label files.

• provideDefault - When true, the module provider returns the label reference as the value for any label it can't find. When false, the module provider returns undefined for labels it can't find. This lets any module providers called afterward attempt to resolve the request.
• labelDirs - An array of one or more label package namespaces and their locations in the project directory.

{
    "moduleProviders": [
        // Start of Label Module Provider configuration
        [
            "@lwrjs/label-module-provider",
            {
                "provideDefault": true,
                "labelDirs": [
                    {
                        "dir": "$rootDir/src/labels",   // Filepath
                        "package": "@my/label"          //
                    }
                ]
            }
        ],
        // End of Label Module Provider configuration
         "@lwrjs/app-service/moduleProvider",
    ]
}

If you don't specify a value for dir or package, the module provider uses the following configuration by default.

{
    "provideDefault": false,
    "labelDirs": [
        {
            "dir": "$rootDir/src/labels",
            "package": "@salesforce/label"
        }
    ]
}

Import Labels into a Component

After you create your label files and configure the Label Module Provider, you can import labels into your components.

Here's an example of an app that displays a localized string (greeting) on its homepage. The Label Module Provider returns the label value from the file corresponding to the requested locale.

<!-- app.html -->
<template>
    <h1>{greeting}</h1>
</template>

import { LightningElement } from 'lwc';
import GREETING from '@my/label/home.greeting';

export default class LocalizedApp extends LightningElement {
    greeting = GREETING;
}

In this example:

• import GREETING from '@my/label/home.greeting' determines the language of the text that's displayed on the homepage.
• @my/label is the package namespace configured through the Label Module Provider
• home.greeting is the label reference in the label files. It's in the format of a property selector for label JSON file.

Import Labels into a Template

Templates can't access the Label Module Provider. To pass translated strings into static templates, use a route handler. Templates have access to the viewParams returned by the route handler.

import type { HandlerContext, LocalizedViewRequest, RouteHandlerViewResponse } from '@lwrjs/types';

const DEFAULT_LOCALE = 'en';

function getViewParams(locale: string, rootDir: string): { title: string; language: string } {
    // Get the translated string from the file system, a database, etc.
}

// Return translated strings to be used in the layout template
export default function translationRouteHandler(
    viewRequest: LocalizedViewRequest,
    context: HandlerContext,
): RouteHandlerViewResponse {
    const locale = viewRequest.locale || DEFAULT_LOCALE;
    const params = getViewParams(locale, context.rootDir);
    return {
        view: {
            // This layout template uses the viewParams
            layoutTemplate: '$rootDir/src/layout.html',
        },
        viewParams: {
            // available as {{title}} or {{page.title}} in the layout template
            title: params.title,
            // available as {{language}} in the layout template
            language: params.language,
        },
    };
}

<!doctype html>
<html lang="{{language}}">
    <head>
        <title>{{title}}</title>
    </head>
    <body>
        <example-app></example-app>
        {{{lwr_resources}}}
    </body>
</html>