Qwik Speak
  • README
  • Library
    • 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
  • Tools​
    • Qwik Speak Extract
    • Qwik Speak Inline Vite plugin
Powered by GitBook
On this page
  • Getting Started
  • Overview
  • Getting the translation
  • Getting dates, relative time & numbers
  • Static translations
  • Extraction of translations
  • Automatic translation
  • Speak context
  • Speak config
  • SpeakLocale
  • Translation functions
  • Translation
  • APIs
  • Providers
  • Context
  • Translate
  • Localize
  • Routing
  • Testing
  • Development Builds
  • Library & tools
  • Sample app
  • Watch mode
  • License
Edit on GitHub

README

NextQuick Start

Last updated 11 months ago

Internationalization (i18n) library to translate texts, dates and numbers in Qwik apps

npm install qwik-speak --save-dev

Getting Started

Live example on and playground on

Overview

Getting the translation

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 */}
    </>
  );
});

You can pass only the default values by enabling the automatic key generation option:

import { inlineTranslate } from 'qwik-speak';

export default component$(() => {
  const t = inlineTranslate();

  return (
    <>
      <h1>{t('Qwik Speak')}</h1> {/* Qwik Speak */}
      <p>{t('Hi! I am {{name}}', { name: 'Qwik Speak' })}</p> {/* Hi! I am Qwik Speak */}
    </>
  );
});

Getting dates, relative time & numbers

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 */}
    </>
  );
});

Static translations

Translation are loaded and inlined in chunks sent to the browser during the build.

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.

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 fallback

  • supportedLocales List of locales supported by the app

  • assets Translation file names. Each asset is passed to the loadTranslation$ function to obtain data according to the language

  • runtimeAssets Assets available at runtime

  • keySeparator Separator of nested keys. Default is .

  • keyValueSeparator Key-value separator. Default is @@

  • rewriteRoutes Rewrite routes as specified in Vite config for qwikCity plugin

  • domainBasedRouting Domain-based routing options

  • showDebugMessagesLocally Whether to enable local debugging mode. Default is true

SpeakLocale

The SpeakLocale object contains the lang, in the format language[-script][-region], where:

  • language ISO 639 two-letter or three-letter code

  • script ISO 15924 four-letter script code

  • region ISO 3166 two-letter, uppercase code

and optionally contains:

  • extension Language with Intl extensions, in the format language[-script][-region][-extensions] like en-US-u-ca-gregory-nu-latn to format dates and numbers

  • currency ISO 4217 three-letter code

  • timeZone From the IANA time zone database

  • units Key value pairs of unit identifiers

  • dir Text direction: 'ltr' | 'rtl' | 'auto'

  • domain In domain-based routing, set the default domain for the locale

  • withDomain 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 config

  • translationFn Optional functions to use

  • langs Optional additional languages to preload data for (multilingual)

  • currency Optional currency if different from the current one

  • timeZone Optional time zone if different from the current one

useSpeak(props: SpeakProps) can be used for lazy loading translation. SpeakProps:

  • assets Assets to load

  • runtimeAssets Assets to load available at runtime

  • langs Optional additional languages to preload data for (multilingual)

Context

  • useSpeakContext() Returns the Speak state

  • useSpeakConfig() Returns the configuration in Speak context

  • useSpeakLocale() 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 is key@@[default value]

Localize

Routing

  • 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) Validate language[-script][-region]

  • extractFromUrl(route: URL) Extract prefix from url

  • extractFromDomain(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

cd packages/qwik-speak
npm install
npm run build

Test

npm test

Sample app

Run

npm install
npm start

Preview

npm run preview

Test

npm test
npm run test.e2e

Watch mode

npm run dev

License

MIT

See and for more details.

See for more details.

See for more information on how it works and how to use it.

See for more information on how to use it.

inlinePlural: () => (value: number | string, key?: string, params?: Record<string, any>, options?: Intl.PluralRulesOptions, lang?: string) Gets the plural by a number using API

useFormatDate: () => (value: Date | number | string, options?: Intl.DateTimeFormatOptions, lang?: string, timeZone?: string) Formats a date using API

useRelativeTime: () => (value: number | string, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions, lang?: string) Formats a relative time using API

useFormatNumber: () => (value: number | string, options?: Intl.NumberFormatOptions, lang?: string, currency?: string) Formats a number using API

useDisplayName: () => (code: string, options: Intl.DisplayNamesOptions, lang?: string) Returns the translation of language, region, script or currency display names using API

Qwik Speak Inline Vite plugin
Qwik Speak Extract
GPT Translate JSON
Qwik Speak DeepL
Intl.PluralRules
Intl.DateTimeFormat
Intl.RelativeTimeFormat
Intl.NumberFormat
Intl.DisplayNames
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
Cloudflare pages
CodeSandbox
Translate
Automatic key generation
Localize