README
Internationalization (i18n) library to translate texts, dates and numbers in Qwik apps
Getting Started
Live example on Cloudflare pages and playground on CodeSandbox
Overview
Getting the translation
You can pass only the default values by enabling the automatic key generation option:
See Translate and Automatic key generation for more details.
Getting dates, relative time & numbers
See Localize for more details.
Static translations
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.
Extraction of translations
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.
Automatic translation
To automatically translate files, the following external packages are available:
Speak context
SpeakState
is immutable: it cannot be updated after it is created and is not reactive
Speak config
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
SpeakLocale
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
Translation functions
TranslationFn
interface can be implemented to change the behavior of the library:
loadTranslation$
QRL function to load translation data
Translation
Translation
contains only the key value pairs of the translation data provided with the runtimeAssets
APIs
Providers
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)
Context
useSpeakContext()
Returns the Speak stateuseSpeakConfig()
Returns the configuration in Speak contextuseSpeakLocale()
Returns the locale in Speak context
Translate
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
Localize
useFormatDate: () => (value: Date | number | string, options?: Intl.DateTimeFormatOptions, lang?: string, timeZone?: string)
Formats a date using Intl.DateTimeFormat APIuseRelativeTime: () => (value: number | string, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions, lang?: string)
Formats a relative time using Intl.RelativeTimeFormat APIuseFormatNumber: () => (value: number | string, options?: Intl.NumberFormatOptions, lang?: string, currency?: string)
Formats a number using Intl.NumberFormat APIuseDisplayName: () => (code: string, options: Intl.DisplayNamesOptions, lang?: string)
Returns the translation of language, region, script or currency display names using Intl.DisplayNames API
Routing
localizePath: () => (route: (string | URL) | string[], lang?: string)
Localize a path, an URL or an array of paths with the languagetranslatePath: () => (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 onevalidateLocale(lang: string)
Validatelanguage[-script][-region]
extractFromUrl(route: URL)
Extract prefix from urlextractFromDomain(route: URL, domains: SpeakLocale[] | RewriteRouteOption[])
Extract lang/prefix from domain
Testing
QwikSpeakMockProvider
component provides the Speak context to test enviroments
Development Builds
Library & tools
Build
Test
Sample app
Run
Preview
Test
License
MIT
Last updated