utils.mergeI18n()

The utils.mergeI18n() function merges translation files from different designs.

When your design re-uses parts from other designs, it should provide translation for those parts and any strings or options they use. Rather than re-creating this content in your own design, you can pull it out of of the design you are using the part from by importing the i18n named export, and then use this function to merge it with your own translations.

Signature

Object mergeI18n({
  Array designs,
  Object options
})

Use

In its simplest form, this function will receive an Array of translation data (typically the i18n named export of a design) and merge them:

import { i18n as brianI18n } from '@freesewing/brian'
import { i18n as simonI18n } from '../i18n/index.mjs'

// Merge translations
const i18n = mergeI18n([brianI18n, simonI18n])

This simple approach is typically what you want when you are extending a design and you are keeping all the parts and options of the design you are extending. In the example above, Simon extends Brian in this way.

Configuration

If you don’t want to keep all options or parts, you can further control how the translation data will be merged by passing in a second parameter which is an object holding the configuration that describes how to merge the translation data.

The configuration object takes 3 top-level properties:

• s: Specifies configuration for how to merge the translation of strings (under s in the translation files)
• p: Specifies configuration for how to merge the part name translations (under p in the translation files)
• o: Specifies configuration for how to merge the option translations (under p in the translation files)

For each of the s, p, and o keys you can specify the following properties:

• drop: An Array with the keys of entries to not merge (drop). Keys that are not in this array will be merged.
• keep: An Array with the keys of entries to merge (keep). Keys that are not in this array will not be merged.

Example

import { i18n as brianI18n } from '@freesewing/brian'
import { i18n as otherI18n } from '../i18n/index.mjs'

// Merge translations
const i18n = mergeI18n(
  [brianI18n, otherI18n],
  {
    p: {
      keep: ['sleevecap'],
    },
    o: {
      drop: ['waistEase', 'chestEase']
      }
    }
  }
)

The function will check each key under the s, p, and o top-level keys in the translation files. For each it will:

• Check whether there is a drop array configured. If there is, it will remove the entry if its key is included in the drop Array.
• Check whether there is a keep array configured. If there is, it will remove the entry if its key is not included in the keep Array.

If the entry is not explicitly removed by including it in drop or excluding it from a list set in keep it will be kept.