translate.md

Translate

All translation functions, except $inlineTranslate, use the Speak context internally: they must be used within the Qwik components

$translate

The $translate function is responsible for translating, extracting to external files, and inlining during the build, using key-value pairs:

$translate('home.title@@Qwik Speak')

• In dev mode, the function returns the default value (value after @@) if provided

• When extracting translations, it creates scoped translation files:

  home.json

  {
    "home": {
      "title": "Qwik Speak"
    }
  }

• After extraction, it returns the value in files

• In prod mod, using Qwik Speak Inline Vite plugin, $translate function is replaced by its translation in chunks sent to the browser:

  `Qwik Speak`

Params interpolation

$translate function accept params as well:

$translate('home.greeting@@Hi! I am {{name}}', { name: 'Qwik Speak' })

name param is replaced at runtime or during the inlining:

Hi! I am Qwik Speak

Array of keys

$translate function accepts array of keys:

$translate(['value1@@Value 1', 'value2@@Value 2'])

and returns an array of translated values:

["Value 1", "Value 2"]

Arrays and objects as values

It can get arrays and objects directly from files:

{
  "home": {
    "array": [
      "one",
      "two",
      "three"
    ],
    "obj": {
      "one": "1",
      "two": "2"
    }
  }
}

just pass to the function the type parameter:

import type { Translation } from 'qwik-speak';

$translate<string[]>('home.array')
$translate<Translation>('home.obj')

Finally, it is possible to set arrays and objects passing a valid stringified default value:

$translate<string[]>('home.array@@["one","two","three"]')
$translate<Translation>('home.obj@@{"one":"1","two":"2"}')

You can also access by array position:

$translate('home.array.2@@three')

To reduce complexity (arrays and objects are inlined during build) it is recommended to use objects with a depth not greater than 1. For the same reason, params interpolation is not supported when you return an array or an object

$inlineTranslate

The $inlineTranslate function has the same behavior as $translate, but can be used outside the component$, for example in Inline components, passing the Speak context as second argument:

import { $inlineTranslate, useSpeakContext } from 'qwik-speak';

export const MyComponent = (props: { ctx: SpeakState }) => {
  return <h1>{$inlineTranslate('home.title@@Qwik Speak', props.ctx)}</h1>;
};

export const Home = component$(() => {
  const ctx = useSpeakContext();

  return (
    <>
      <MyComponent ctx={ctx} />
    </>
  );
});

$plural

The $plural function uses the Intl.PluralRules API:

p(1, 'home.devs')

When you run the extraction tool, it creates a translation file with the Intl API plural rules for each language:

{
  "home": {
    "devs": {
      "one": "",
      "other": ""
    }
  }
}

There is no default value for the $plural function, so you must add the translation in each language, keeping in mind that the counter is optionally interpolated with the value parameter:

{
  "home": {
    "devs": {
      "one": "{{ value }} software developer",
      "other": "{{ value }} software developers"
    }
  }
}

It is rendered as:

1 software developer

useTranslate$

The useTranslate$ closure returns the translate function as QRL. This means that it is serializable and it can be passed to other QRL functions characterized by lazy loading:

import { useTranslate$ } from 'qwik-speak';

const MyComponent = component$(() => {
  const t$ = useTranslate$();

  const s = useSignal('');

  return (
      <button onClick$={async () => s.value = await t$('runtime.test')}></button>
  );
});

The translation keys passed into its must be provided in runtimeAssets and will not be inlined

Localize

All localization functions use the Speak context internally: they must be used within the Qwik components

formatDate

The formatDate function uses the Intl.DateTimeFormat API:

formatDate(Date.now(), { dateStyle: 'full', timeStyle: 'short' })

The second param in the signature is an Intl DateTimeFormatOptions object, which allows you to customize the format:

Monday, March 6, 2023 at 12:20 PM

Optionally it uses the time zone set in timeZone property of the SpeakLocale.

relativeTime

The relativeTime function uses the Intl.RelativeTimeFormat API:

relativeTime(-1, 'second')

The second param in the signature is an Intl RelativeTimeFormatUnit string:

1 second ago

formatNumber

The formatNumber function uses the Intl.NumberFormat API:

formatNumber(1000000)

1,000,000

Currency

To format as currency, you have to set the style property of the second param, an Intl NumberFormatOptions object:

formatNumber(1000000, { style: 'currency' })

$1,000,000.00

It uses the currency code set in currency property of the SpeakLocale.

Unit

To format as unit, you have to set the style and unit properties of the second param:

const locale = useSpeakLocale();
const units = locale.units!;

formatNumber(1, { style: 'unit', unit: units['length'] })

1 mi

It uses the unit set in optional units property of the SpeakLocale:

units: { 'length': 'mile' }

displayName

The displayName function uses the Intl.DisplayNames API:

displayName('en-US', { type: 'language' })

American English

The locale used by formatDate, relativeTime, formatNumber and displayName is primarily the extension property of the SpeakLocale if provided, otherwise the lang property. extension is the language with Intl extensions, in the format language[-script][-region][-extensions] like en-US-u-ca-gregory-nu-latn

Multilingual

Each of the translation and localization functions accepts a different language other than the current one as its last argument:

$translate('home.title@@Qwik Speak', undefined, 'it-IT')

For the translation to occur in the language passed as an argument, you need to pass the additional language to QwikSpeakProvider or Speak components:

<Speak assets={['home'] langs=['it-IT']}>
  <Home />
</Speak>