Qwik Speak

A SpeakLocale object represents a specific language setting. It follows the format language[-script][-region].

Core Fields:

• language: ISO 639 two-letter or three-letter code.
• script: ISO 15924 four-letter script code.
• region: ISO 3166 two-letter, uppercase code.

Optional Fields:

• extension: Language with Intl extensions (e.g., en-US-u-ca-gregory-nu-latn).
• currency: ISO 4217 three-letter code.
• timeZone: IANA time zone database name.
• units: Key-value pairs of unit identifiers.
• dir: Text direction ('ltr' | 'rtl' | 'auto').
• domain: Default domain for the locale in domain-based routing.
• withDomain: Alternative domain for the locale in domain-based routing.

The qwik-speak/inline plugin optimizes translation performance by shifting the translation work from runtime to compile-time for the client.

• On the Server (SSR): Translations happen at runtime. Assets are loaded during SSR, and lookups occur dynamically.
• On the Client: Translations happen at compile-time. Assets are loaded and inlined directly into the JavaScript chunks sent to the browser during the build process. This reduces runtime resource usage.
• Runtime Assets: Assets designated as runtimeAssets are always loaded at runtime on both the server and the client, enabling dynamic translations that cannot be inlined at build time.

Add the qwikSpeakInline plugin to your vite.config.ts to enable inline translation support. You must specify supportedLangs, a defaultLang, and the assetsPath where your translation files are located.

import { qwikSpeakInline } from 'qwik-speak/inline';

export default defineConfig(() => {
  return {
    plugins: [
      qwikCity(),
      qwikVite(),
      qwikSpeakInline({
        supportedLangs: ['en-US', 'it-IT'],
        defaultLang: 'en-US',
        assetsPath: 'i18n'
      }),
      tsconfigPaths(),
    ],
  };
});

You can extract all used translation keys into JSON files for production. This process generates files in your specified assetsPath (e.g., i18n/en-US/app.json).

Note on Dynamic Keys: Keys that are constructed dynamically at runtime (e.g., `runtime.${key}`) will be skipped by the extractor. These must be manually added to your runtimeAssets files (e.g., i18n/[lang]/runtime.json).

Command: Add a script to your package.json to run the extraction:

# Example script entry
"qwik-speak-extract": "qwik-speak-extract --supportedLangs=en-US,it-IT --assetsPath=i18n"

Then run:

npm run qwik-speak-extract

Run the standard build command to generate the static files. After the build completes, inspect the dist folder to verify that an index.html exists for every page in every supported language.

npm run build

To automatically detect and set the locale on every request, implement an onRequest handler in a plugin.ts file within your src/routes directory. You must call the locale() function provided by Qwik City to set the active language.

Common strategies include:

• Parsing the accept-language header.
• Reading from a cookie.
• Reading from a URL parameter.

import type { RequestHandler } from '@builder.io/qwik-city';
import { config } from '../speak-config';

export const onRequest: RequestHandler = ({ request, locale }) => {
  const acceptLanguage = request.headers?.get('accept-language');

  let lang: string | null = null;

  if (acceptLanguage) {
    lang = acceptLanguage.split(';')[0]?.split(',')[0];
  }

  lang = config.supportedLocales.find(value => value.lang === lang)?.lang || config.defaultLocale.lang;

  locale(lang);
};

Functions like routeLoader$ or endpoints run on the server and may not have access to the application's translation context. To translate in these environments, use the server$ function. You must ensure the server knows the current language, typically by passing the locale as a parameter from the client or extracting it from the request (cookies/params).

export const serverFn = server$(function (lang: string) {
  const t = inlineTranslate();
  return t('title', { name: 'Qwik Speak' }, lang);
});

export default component$(() => {
  const locale = useSpeakLocale();
  const s = useSignal('');

  useTask$(async () => {
    s.value = await serverFn(locale.lang);
  });

  return (<p>{s.value}</p>);
});

If a translation key is determined at runtime (e.g., t(dynamicKey)), it cannot be evaluated at compile time. To support this, you must:

1. Create a runtime.json file in your language directory (e.g., i18n/[lang]/runtime.json).
2. Add the path to this file in the runtimeAssets configuration of your useSpeak provider.

// i18n/[lang]/runtime.json
{
  "dynamic": "I'm a dynamic value"
}

To clean up your translation files by removing keys that are no longer used in your components, enable the --unusedKeys option. You must also provide a comma-separated list of --runtimeAssets to ensure that files used at runtime are not purged.

Example CLI command:

npm run qwik-speak-extract -- --supportedLangs=en-US,it-IT --unusedKeys=true --runtimeAssets=runtime