Internationalization (i18n) library to translate texts, dates and numbers in Qwik apps
npm install qwik-speak --save-dev
- Quick Start
- Tutorial: localized routing with the language
- Tutorial: translated routing with url rewriting
- Translate
- Translation functions
- Lazy loading translation
- Qwik Speak and Adapters
- Testing
Live example on Cloudflare pages and playground on CodeSandbox
import { inlineTranslate } from 'qwik-speak';
export default component$(() => {
const t = inlineTranslate();
return (
<>
<h1>{t('title@@Qwik Speak')}</h1> {/* Qwik Speak */}
<p>{t('greeting@@Hi! I am {{name}}', { name: 'Qwik Speak' })}</p> {/* Hi! I am Qwik Speak */}
</>
);
});
import { useFormatDate, useRelativeTime, useFormatNumber } from 'qwik-speak';
export default component$(() => {
const fd = useFormatDate();
const rt = useRelativeTime();
const fn = useFormatNumber();
return (
<>
<p>{fd(Date.now(), { dateStyle: 'full', timeStyle: 'short' })}</p> {/* Wednesday, July 20, 2022 at 7:09 AM */}
<p>{rt(-1, 'second')}</p> {/* 1 second ago */}
<p>{fn(1000000, { style: 'currency' })}</p> {/* $1,000,000.00 */}
</>
);
});
Translation are loaded and inlined in chunks sent to the browser during the build.
See Qwik Speak Inline Vite plugin for more information on how it works and how to use it.
To extract translations directly from the components, a command is available that automatically generates the files with the keys and default values.
See Qwik Speak Extract for more information on how to use it.
To automatically translate files, an external command is available that uses OpenAI GPT Chat Completions API.
See GPT Translate JSON for more information on how to use it.
stateDiagram-v2
State1: SpeakState
State2: SpeakConfig
State3: SpeakLocale
State4: TranslationFn
State5: Translation
State1 --> State2
State1 --> State3
State1 --> State4
State1 --> State5
note right of State2: configuration
note right of State3
- lang
- extension (Intl)
- currency
- timezone
- unit
- dir
- domain
end note
note right of State4
- loadTranslation$
end note
note right of State5
runtime assets
end note
SpeakState
is immutable: it cannot be updated after it is created and is not reactive
defaultLocale
The default locale to use as fallbacksupportedLocales
List of locales supported by the appassets
Translation file names. Each asset is passed to theloadTranslation$
function to obtain data according to the languageruntimeAssets
Assets available at runtimekeySeparator
Separator of nested keys. Default is.
keyValueSeparator
Key-value separator. Default is@@
rewriteRoutes
Rewrite routes as specified in Vite config forqwikCity
plugindomainBasedRouting
Domain-based routing options
The SpeakLocale
object contains the lang
, in the format language[-script][-region]
, where:
language
ISO 639 two-letter or three-letter codescript
ISO 15924 four-letter script coderegion
ISO 3166 two-letter, uppercase code
and optionally contains:
extension
Language with Intl extensions, in the formatlanguage[-script][-region][-extensions]
likeen-US-u-ca-gregory-nu-latn
to format dates and numberscurrency
ISO 4217 three-letter codetimeZone
From the IANA time zone databaseunits
Key value pairs of unit identifiersdir
Text direction:'ltr' | 'rtl' | 'auto'
domain
In domain-based routing, set the default domain for the localewithDomain
In domain-based routing, set another domain for the locale
TranslationFn
interface can be implemented to change the behavior of the library:
loadTranslation$
QRL function to load translation data
Translation
contains only the key value pairs of the translation data provided with the runtimeAssets
useQwikSpeak(props: QwikSpeakProps)
provides the Speak context to the app. QwikSpeakProps
:
config
Speak configtranslationFn
Optional functions to uselangs
Optional additional languages to preload data for (multilingual)currency
Optional currency if different from the current onetimeZone
Optional time zone if different from the current one
useSpeak(props: SpeakProps)
can be used for lazy loading translation. SpeakProps
:
assets
Assets to loadruntimeAssets
Assets to load available at runtimelangs
Optional additional languages to preload data for (multilingual)
useSpeakContext()
Returns the Speak stateuseSpeakConfig()
Returns the configuration in Speak contextuseSpeakLocale()
Returns the locale in Speak context
-
inlineTranslate: () => (keys: string | string[], params?: Record<string, any>, lang?: string)
Translates a key or an array of keys. The syntax of the string iskey@@[default value]
-
inlinePlural: () => (value: number | string, key?: string, params?: Record<string, any>, options?: Intl.PluralRulesOptions, lang?: string)
Gets the plural by a number using Intl.PluralRules API
-
useFormatDate: () => (value: Date | number | string, options?: Intl.DateTimeFormatOptions, lang?: string, timeZone?: string)
Formats a date using Intl.DateTimeFormat API -
useRelativeTime: () => (value: number | string, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions, lang?: string)
Formats a relative time using Intl.RelativeTimeFormat API -
useFormatNumber: () => (value: number | string, options?: Intl.NumberFormatOptions, lang?: string, currency?: string)
Formats a number using Intl.NumberFormat API -
useDisplayName: () => (code: string, options: Intl.DisplayNamesOptions, lang?: string)
Returns the translation of language, region, script or currency display names using Intl.DisplayNames API
-
localizePath: () => (route: (string | URL) | string[], lang?: string)
Localize a path, an URL or an array of paths with the language -
translatePath: () => (route: (string | URL) | string[], lang?: string)
Translates a path, an URL or an array of paths. The translating string can be in any language. If not specified the target lang is the current one -
validateLocale(lang: string)
Validatelanguage[-script][-region]
-
extractFromUrl(route: URL)
Extract lang from url -
extractFromDomain(route: URL, domains: SpeakLocale[] | RewriteRouteOption[])
Extract lang from domain
QwikSpeakMockProvider
component provides the Speak context to test enviroments
cd packages/qwik-speak
npm install
npm run build
npm test
npm install
npm start
npm run preview
npm test
npm run test.e2e
MIT