loc

Updated:
Supported Platforms:
UUX

Looks up strings by key in the language dictionary

The loc() function - short for localization - looks up strings in the language dictionary using the provided arguments and returns their translated value.

A popular web component variant which renders the translated text is also available: q2-loc.

Details

Type

/* Returns the value associated with the provided key in the translation dictionary */

tecton.sources.loc(
  key: string,
  substitutions?: IDict<any> | string[],
  overrideFormatsAndOptions?: Partial<Formats & Options>,
  options?: Options
): string;

Example

// In translations dictionary

translations: {
  "styleGuide.components.q2Loc.greetingExample": "Hello there!"
}

// In JS file or script tag

// returns the translated string (e.g. "Hello There!")
tecton.sources.loc('styleGuide.components.q2Loc.greetingExample');

Using plural formatting

Given a translation string like this:

{
  "errorMessage.header": "There {errorCount, plural, =1 {is one error}, other {are # errors}}"
}

You can use the loc capability to return singular or plural messages.

tecton.sources.loc(`errorMessage.header`, { errorCount: 1 })
// => "There is one error"

tecton.sources.loc(`errorMessage.header`, { errorCount: 3 })
// => "There are 3 errors"

Using date, time, and number formatting

The loc capability allows you to easily format dates, times, and numbers in your web applications. With support from the FormatJS API, you can ensure that your formatting is accurate and localized for your project.

Example

Given a list of translation strings like these:

{
  "tecton.number": "The price is: {value, number, options}",
  "tecton.date": "The date is: {value, date, options}",
  "tecton.time": "The time is: {value, time, options}"
}

You can use the loc capability to return formatted values.

tecton.sources.loc(
  'tecton.number',
  { value: 1776.67 },
  { number: { options: { style: 'currency', currency: 'USD' } } }
)
// => "The price is: $1,776.67"

tecton.sources.loc(
  'tecton.date',
  { value: new Date(Date.UTC(2015, 3, 10, 15, 0, 0)) },
  { date: { options: { dateStyle: 'medium', timeZone: 'UTC' } } }
)
// => "The date is: Apr 10, 2015"

tecton.sources.loc(
  'tecton.time',
  { value: new Date(Date.UTC(2015, 3, 10, 15, 0, 0)) },
  { time: { options: { timeStyle: 'medium', timeZone: 'UTC' } } }
)
// => "The time is: 3:00:00 PM"

Options

The options object for each format type takes any of the properties that are exposed in their respective APIs:

  • Number: Intl.NumberFormatOptions (Link)
  • Date: Intl.DateTimeFormat (Link)
  • Time: Intl.DateTimeFormat (Link)

Arguments

UUX

Used to look up the desired message in the current language file. The message value may use ICU message syntax.

UUX

An object containing the substitutions if an ICU message is expected.

UUX

Allows you to provide special formatting for numbers/currents, dates, and times. Each type uses its native respective JS API. See FormatJS for more information.

Type

interface Formats {
  number: Record<string, NumberFormatOptions>;
  date: Record<string, Intl.DateTimeFormatOptions>;
  time: Record<string, Intl.DateTimeFormatOptions>;
}

Example

JSON

{
  "tecton.date": "{value, date, options}",
}

JS

tecton.sources.loc(
  'tecton.date',
  { value: new Date(Date.UTC(2015, 3, 10, 15, 0, 0)) },
  { date: { options: { dateStyle: 'medium', timeZone: 'UTC' } } }
)
// Returns: "The date is: Apr 10, 2015"
UUX

An object containing options to pass to the underlying formatters. See Intl MessageFormat for more details.

Type

interface Options {
  formatters?: Formatters;
  ignoreTag?: boolean;
}

Frequency Asked Questions

There is 1 frequently asked question related to this page.

Release Notes

Initial Release