LocalizationManager
Encapsulates the setup required for customizing and adding additional entries to the localization dictionary
Disclaimer: This component was built by the community at large and is not an official Coveo JSUI Component. Use this component at your own risk.
Prerequisites
-
@coveops/cli
version 0.10.0 or later must be installed to support localization with this component.
Getting Started
- Install the component into your project.
npm i @coveops/localization-manager
- Use the Component or extend it
Typescript:
import * as LocalizationManager from '@coveops/localization-manager';
Javascript
const LocalizationManager = require('@coveops/localization-manager');
- You can also expose the component alongside other components being built in your project.
export * as LocalizationManager from '@coveops/localization-manager'
- Or for quick testing, you can add the script from unpkg
<script src="https://unpkg.com/@coveops/localization-manager@latest/dist/index.min.js"></script>
Disclaimer: Unpkg should be used for testing but not for production.
- Expose the custom locale file using a script tag.
This locale should correspond to the one you used with Coveo.
<script src="https://static.cloud.coveo.com/searchui/v2.8864/js/cultures/fr.js"></script>
The locales must match in order for localization to work. This can be automated using backend template rendering where suited by replacing the locale with a variable as relevant.
<script src="locales/fr.js"></script>
Adding the locales file generated by the build will expose a global LOCALES
variable that can then be passed to the LocalizationManger
to manage the remaining steps for you.
- Include the component in your template as follows:
Add the following execution to your code once the page has initialized:
<script>
CoveoLocalizationManager(LOCALES)
</script>
If the component is being bundled amongst other components, it will be available on the Coveo object.
<script>
Coveo.LocalizationManager(LOCALES)
</script>
Be sure to update the variables to have the relevant information.
Options
The following options can be configured:
Option | Required | Type | Default | Notes |
---|---|---|---|---|
locales |
Yes | object | An object containing all of the translations for the given locale. | |
components |
No | string[] | An array of component names to target ex: DynamicFacet
|
|
searchInterface |
No | Element | The search interface to target when setting up localization. By default, all search interfaces on the page will be targeted. | |
options |
No | object | {} | An object with additional options to configure as detailed in the following entries |
options.disableTargetting |
No | boolean | false |
Tells the localization manager to only set the global translation dictionary and not to pass the definitions as valueCaptions to targeted components. A targeted component can be specified with the components option or by specifying the target option with the create:translation command. |
Managing Translations
With this component installed, and @coveops/cli
version 0.10.0 or newer, the following CLI commands can be used to add localization to your project:
- Add locales for the languages you will support. Adding another language later on will create placeholders from your default language. By default the CLI uses
en
.
npx @coveops/cli create:locales en fr
- Add translations for terms you want to replace.
npx @coveops/cli create:translation City --en City --fr Ville
- Override translation terms for a given component or element with a queryable id.
npx @coveops/cli create:translation City --en City --fr Ville --target DynamicFacet
Contribute
- Clone the project
- Copy
.env.dist
to.env
and update the COVEO_ORG_ID and COVEO_TOKEN fields in the.env
file to use your Coveo credentials and SERVER_PORT to configure the port of the sandbox - it will use 8080 by default. - Build the code base:
npm run build
- Serve the sandbox for live development
npm run serve