loc

Updated:
Supported Platforms:
UUX

Looks up strings by key in the current language file.

The loc() function, short for localization, looks up strings by key in the current language file. It is part of the Tecton language internationalization system. We use the Intl MessageFormat library under the hood, allowing for robust formatting of dynamic messages using the ICU message syntax.

A web component wrapping this function is also available as q2-loc. This variant is the most frequently used, as it puts language directly into HTML.

Details

Type

tecton.sources.loc(
  key: string,
  substitutions?: IDict<any> | string[],
  overrideFormatsAndOptions?: Partial<Formats & Options>,
  options?: Options
): string;
// Returns the value associated with the provided key in the currently selected language file.

Example

tecton.sources.loc('errorMessage.status_200');

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