@sveltekit-i18n/parser-default

@sveltekit-i18n/parser-default

This parser is ment be used together with @sveltekit-i18n/base, but can be used with other libraries as well. In fact, it does not require Svelte or SvelteKit.

IMPORTANT: THIS PACKAGE IS STILL UNDER DEVELOPMENT - API MAY VARY UNTIL 1.0.0

Options

modifierDefaults?: Modifier.Defaults

You can specify default values for built-in modifiers using this prop. Configuration is available for these modifiers:

number?: Intl.NumberFormatOptions
date?: Intl.DateTimeFormatOptions
ago?: Intl.RelativeTimeFormatOptions & { format?: Intl.RelativeTimeFormatUnit | 'auto' }

customModifiers?: Record<string, Modifier.T>

You can use this property to include your own set of modifiers.

For example custom modifier eqAbs...

{
  eqAbs: (value, options, defaultValue, locale) => options.find(({ key }) => Math.abs(key) === Math.abs(value))?.value || defaultValue
}

...can be used in the definitions like this:

{{placeholder:eqAbs; key1:value1; key2:value2; default:defaultValue;}}

Read more about Modifiers.

Syntax

Every placeholder or modifier starts with {{ and ends with }} and can be included in your translations like this:

{
  "simple_prop": "Some value",
  "module": {
    "placeholder": "Title with {{placeholder}}.",
    "placeholder_with_default_value": "{{placeholder; default:Default value;}}.",
    "modifier": "{{gender; female:She; male:He;}} has a dog.",
    "combined": "You have {{number:gt; 0:{{number}} new {{number; 1:message; default:messages;}}!; default:no messages.;}}"
  }
} 

Placeholders

Placeholders work as a connection between static translations and dynamic content. They are usually replaced by dynamic values, which are the same for all language mutations.

Placeholder notation looks like this:

{{placeholder}}

<!-- or: -->
{{placeholder;}}

You can also use default value. This value is used in case there is no appropriate value in translation payload.

{{placeholder; default:This is a default value;}}

The default value can be also set dynamically using the translation payload in your .svelte file. For example:

$t(`error.${code}`, { default: $t('error.default') });

This value is used in case no default value is defined within the placeholder definition itself. For more, see Dynamic default section in parser-default example app.

Modifiers

Modifiers don't represent the payload value directly, but they can use it for further calculations. Currently, these modifiers are in place:

eq – input value is equal to the value in your definition (string comparison, case insensitive).
ne – input value is not equal to the value in your definition (string comparison, case insensitive).
lt – input value is lower than the value in your definition.
lte – input value is lower than or equal to the value in your definition.
gt – input value is greater than the value in your definition.
gte – input value is greater than or equal to the value in your definition.
number – input value is converted to locale formatted number string.
date – input value is converted to locale date string.
ago – input value is converted to locale relative date string.

Each modifier returns a string value based on these input properties:

value: any – interpolated placeholder value
options: {key: string; value: string;}[] – parsed interpolation options from the definition
props?: any – modifier properties
defaultValue?: string – default value
locale?: string – current locale

When placeholder value is not matched and you don't specify the default value, modifier returns an empty string.

Modifier notation looks like this:

{{placeholder:modifier; placeholderVal1:Interpolation value 1; placeholderVal2:Interpolation value 2; ... ; default:Default value;}}

In case you don't specify the modifier, but interpolation options are set, eq modifier is used by default:

{{placeholder; placeholder_value:Interpolation value;}}

For example this definition...

// `content` translation definition
{
  "modifier_date": "{{value:date;}}"
}

...you can execute like this:

// svelte file

$t('content.modifier_date', { value: Date.now() }, { timeStyle: 'full' });

// $t(`key`, ...params: [payload, props]);

You are allowed to use nested placeholders and modifiers within your modifier definition or include your own modifiers in Options! See parser-default example in Examples.

Note that ;, :, { and } characters are used as placeholder identifiers and separators, so you shouldn't use them within your definition keys and values. You should use their escaped form insead (\\;, \\:, \\{ or \\}).

Issues

If you are facing issues with this parser, create a ticket here.