Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@cerner/terra-aggregate-translations

Package Overview
Dependencies
Maintainers
7
Versions
13
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@cerner/terra-aggregate-translations

The terra-aggregate-translations pre-build tool assists with creating the translation, intl loader and translation loader files that are configured for the specified locales. This tool is offered as a CLI script and as a setup function.

  • 3.4.0
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
39
decreased by-46.58%
Maintainers
7
Weekly downloads
 
Created
Source

Terra Aggregate Translations

NPM version Build Status Dependencies status devDependencies status

Aggregate Translations Tool

This module provides the aggregate-translations pre-build tool to assist with creating the translation and loader files needed for internationalized Terra components to render correctly.

The terra-aggregate-translations pre-build tool will aggregate the translations, and create the intl loader and translation loader files that are configured for the specified locales. This tool is offered as a CLI script and as a setup function.

How It Works

This script globs the specified translation directory regex pattern(s) to locate the translation directories. Then, for each specified locale, the message-translation pairs from each translation json is extracted and added to the locale's message hash. When all messages have been extracted, the aggregate-translations script will create a single translation javascript file for each locale that exports the messages object, areTranslationsLoaded boolean and locale string. When a translation is missing for a region-specific locale, the message will fallback to the translation defined by the base locale. When a translation file is requested by terra-i18n's I18nProvider, this information is returned and used to provide the locale information.

Once all of the translation files are created for the specified locales, the script will create an intl loader and translation loader that is specific to the specified locales. This is utilized by the by terra-i18n's I18nLoader to load on-demand locale information.

Translation Format

Translations are expected to be provided in a key / value format in a JSON file. A sample translations file looks like the following:

en.json

{
  "MyApp.alert.dismiss": "Dismiss",
  "MyApp.alert.info": "Information.",
  "MyApp.alert.error": "Error.",
  "MyApp.alert.warning": "Warning.",
  "MyApp.alert.alert": "Alert.",
  "MyApp.alert.advisory": "Advisory.",
  "MyApp.alert.success": "Success."
}

Order of Operations

  • Start with default search patterns
  • Add any custom directories to the list of default search patterns to get an intermediate list of directories to search
  • Filter out any directories provided in the excludes option from the intermediate list of directories to search

aggregate-translations Options

OptionCLI OptionTypeDescriptionDefault
baseDir-b, --baseDirPathDirectory to search from and to prepend to the output directory.current working directory
directories-d, --directoriesArray of StringsTranslation directory regex pattern(s) to glob, in addition to the default search patterns.[ ]
excludes-e, --excludesArray of StringsTranslation directory regex pattern(s) to glob exclude from the search patterns.[ ]
outputFileSystemN/AFile System ModuleThe filesystem to use to write the translation and loader files. Note: The file system provide must support mkdirp.fs-extra
locales-l, --localesArray of StringsThe list of locale codes to aggregate. Note: 'en' is always added if not specified.terra-supported locales
outputDir-o, --ouputDirStringOutput directory for the translation and loader files./aggregated-translations
configPath-c, --configStringThe path to the terra i18n configuration fileundefined
format-f, --formatStringThe format of syntax to output the translations with. Possible values are 'es5' and 'es6''es5'
Setup Example

The aggregate-translations setup function can be used as follows:

// webpack config file
const aggregateTranslations = require('@cerner/terra-aggregate-translations');

const aggregateOptions = {
    baseDir: __dirname,
    excludes: ['./node_modules/packageToExclude'],
    locales: ['en', 'en-US'],
    format: 'es6',
};

aggregateTranslations(aggregateOptions);

module.exports = // ...webpack config;
CLI Example

The aggregate-translations CLI is supplied as a bin script, called tt-aggregate-translations, and can be used as follows:

scripts: {
    // ...other scripts
    "aggregate-translations": "tt-aggregate-translations -l ['en','es'] -e ./node_modules/packageToExclude",
    "start:build": "npm run aggregate-translations && npm run start"
}
terraI18n.config Example

Both the setup function and CLI methods allow for the configuration options to be loaded via a config file. The aggregate-translations tool will always attempt to load this config by default. If no config path is provided, the aggregate-translations tool will attempt to load the configuration from ./terraI18n.config.js. If this file does not exist, the default configuration is used.

Add a terra-i18n config file like:

module.exports = {
  locales: ['en', 'en-US'],
};

Then, to load the config someplace other than ./terraI18n.config.js, simply add the config path as follows:

// using setup approach
aggregateTranslations({ configPath: './config/terraI18n.config.js' });

// using CLI approach
"aggregate-translations": "tt-aggregate-translations -c ./config/terraI18n.config.js",

Resolving Translations and Loaders

To provide the aggregated-translations files and loaders as modules to the terra-i18n component, the translated output directory must be supplied the webpack resolve.modules key before 'node_modules' resolution:

 resolve: {
    modules: [path.resolve(__dirname, 'aggregated-translations'), 'node_modules'],
 },

This resolve.modules configuration indicates module resolving occurs in this order:

  1. ./aggregated_translations (or indicated output directory)
  2. ./node_modules

Compiling with ES6 syntax

The aggregate-translations script has the ability to compile with ES6 syntax by setting the format prop to 'es6'. To get these to work properly with Jest and the rest of your configuration, you need to add the babel-plugin-syntax-dynamic-import plugin to your babel configuration. Since we are not using Babel 7 in Terra, you need to use version 6.18.0 to be compatible with our code base.

Usage with Rails/Webpacker

If you are using Rails/Webpacker, you can generate the aggregate-translation files and ensure they resolve correctly when running webpack with the following config setup in app/config/webpack/environment.js file.

const { environment } = require('@rails/webpacker')

const aggregateTranslations = require('@cerner/terra-aggregate-translations');

// generate the 'aggregated-translations' in 'tmp'
aggregateTranslations({
  format: 'es6',
  outputDir: 'tmp/aggregated-translations'
});

// add the 'aggregated-translations' module to the environment
environment.resolvedModules.append('aggregated-translations', 'tmp/aggregated-translations')

module.exports = environment

Node version support

This package was developed and tested using Node 10 up to Node 14. Consumers using Node 16 or greater are advised to use it at their own risk since those versions are not officially supported due to lack of thorough testing.

LICENSE

Copyright 2019 - present Cerner Innovation, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Keywords

FAQs

Package last updated on 02 May 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc