Update docs

Author: robisim74

README.md

@@ -20,9 +20,11 @@ Live example on [Cloudflare pages](https://qwik-speak.pages.dev/) and playground
 ## Overview
 ### Getting the translation
 ```tsx
-import { $translate as t } from 'qwik-speak';
+import { useTranslate } from 'qwik-speak';
 
 export default component$(() => {
+  const t = useTranslate();
+
   return (
     <>
       <h1>{t('app.title@@Qwik Speak')}</h1> {/* Qwik Speak */}
@@ -33,9 +35,13 @@ export default component$(() => {
 ```
 ### Getting dates, relative time & numbers
 ```tsx
-import { formatDate as fd, relativeTime as rt, formatNumber as fn } from '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 */}
@@ -84,7 +90,7 @@ stateDiagram-v2
         of translation data
     end note
 ```
-> `SpeakState` is immutable: it cannot be updated after it is created and is not reactive.
+> `SpeakState` is immutable: it cannot be updated after it is created and is not reactive
 
 - `useSpeakContext()` Returns the Speak state
 - `useSpeakConfig()` Returns the configuration in Speak context
@@ -112,7 +118,7 @@ and optionally contains:
 
 ### Translation functions
 `TranslationFn` interface can be implemented to change the behavior of the library:
-- `loadTranslation$` Function to load translation data
+- `loadTranslation$` QRL function to load translation data
 
 ## APIs
 ### Components
@@ -131,26 +137,26 @@ and optionally contains:
 
 ### Functions
 #### Translate
-- `$translate(keys: string | string[], params?: Record<string, any>, lang?: string)`
+- `useTranslate: () => (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]`
 
-- `$inlineTranslate(keys: string | string[], ctx: SpeakState, params?: Record<string, any>, lang?: string)`
+- `inlineTranslate(keys: string | string[], ctx: SpeakState, params?: Record<string, any>, lang?: string)`
 Translates a key or an array of keys outside the component$. The syntax of the string is `key@@[default value]`
 
-- `$plural(value: number | string, key?: string, params?: Record<string, any>, options?: Intl.PluralRulesOptions, lang?: string)`
+- `usePlural: () => (value: number | string, key?: string, params?: Record<string, any>, options?: Intl.PluralRulesOptions, lang?: string)`
 Gets the plural by a number using [Intl.PluralRules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules) API
 
 #### Localize
-- `formatDate(value: Date | number | string, options?: Intl.DateTimeFormatOptions, lang?: string, timeZone?: string)`
+- `useFormatDate: () => (value: Date | number | string, options?: Intl.DateTimeFormatOptions, lang?: string, timeZone?: string)`
 Formats a date using [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) API
 
-- `relativeTime(value: number | string, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions, lang?: string)`
+- `useRelativeTime: () => (value: number | string, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions, lang?: string)`
 Formats a relative time using [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) API
 
-- `formatNumber(value: number | string, options?: Intl.NumberFormatOptions, lang?: string, currency?: string)`
+- `useFormatNumber: () => (value: number | string, options?: Intl.NumberFormatOptions, lang?: string, currency?: string)`
 Formats a number using [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) API
 
-- `displayName(code: string, options: Intl.DisplayNamesOptions, lang?: string)`
+- `useDisplayName: () => (code: string, options: Intl.DisplayNamesOptions, lang?: string)`
 Returns the translation of language, region, script or currency display names using [Intl.DisplayNames](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames) API
 
 ## Development Builds

docs/inline.md

@@ -1,9 +1,9 @@
 # Qwik Speak Inline Vite plugin
 
-> Inline Qwik Speak `$translate`, `$inlineTranslate` and `$plural` functions at compile time
+> Inline Qwik Speak `useTranslate`, `inlineTranslate` and `usePNrlural` functions at compile time
 
 ## How it works
-In development mode, using Qwik Speak translation happens _at runtime_: `assets` are loaded during SSR or on client, and the lookup also happens at runtime.
+In development mode, translation happens _at runtime_: `assets` are loaded during SSR or on client, and the lookup also happens at runtime.
 
 In production mode, `assets` are loaded only during SSR, and to get the translations on the client as well you have to use _Qwik Speak Inline_ Vite plugin.
 
@@ -80,11 +80,11 @@ Each contains only its own translation:
 
 _dist/build/en-US/q-*.js_
 ```javascript
-/* @__PURE__ */ pr("h2", null, null, `Translate your Qwik apps into any language`, 1, null)
+/* @__PURE__ */ Nr("h2", null, null, `Translate your Qwik apps into any language`, 1, null)
 ```
 _dist/build/it-IT/q-*.js_
 ```javascript
-/* @__PURE__ */ pr("h2", null, null, `Traduci le tue app Qwik in qualsiasi lingua`, 1, null)
+/* @__PURE__ */ Nr("h2", null, null, `Traduci le tue app Qwik in qualsiasi lingua`, 1, null)
 ```
 
 At the end of the build, in root folder a `qwik-speak-inline.log` file is generated which contains:
@@ -95,7 +95,7 @@ At the end of the build, in root folder a `qwik-speak-inline.log` file is genera
 > Note. Currently, only `json` files are supported as assets
 
 ## Qwik Speak Inline Vite plugin & runtime
-When there are translations with dynamic keys or params, that is, they use an identifier, you can manage them in separate files, and add them to `runtimeAssets`:
+When there are translations with dynamic keys or params, you have to use separate files, and add them to `runtimeAssets`:
 
 ```typescript
 export const config: SpeakConfig = {
@@ -108,5 +108,15 @@ export const config: SpeakConfig = {
   ]
 };
 ```
-Likewise, you can also create scoped runtime files for different pages and pass them to `Speak` components.
+Likewise, you can also create scoped runtime files for different pages and pass them to `Speak` components:
+```tsx
+export default component$(() => {
+  return (
+    <Speak assets={['home']} runtimeAssets={['runtimeHome']}>
+      <Page />
+    </Speak>
+  );
+});
+```
+> `runtimeAssets` are serialized and sent to the client, and loaded when required
 

docs/quick-start.md

@@ -45,7 +45,9 @@ export const translationFn: TranslationFn = {
   loadTranslation$: loadTranslation$
 };
 ```
-We have added the Speak config and the implementation of the `loadTranslation$` function. `loadTranslation$` is a customizable function, with which you can load the translation files in the way you prefer.
+We have added the Speak config and the implementation of the `loadTranslation$` function to load translation files.
+
+> `loadTranslation$` is a customizable QRL function: you can load the translation files in the way you prefer
 
 ## Adding Qwik Speak
 Just wrap Qwik City provider with `QwikSpeakProvider` component in `root.tsx` and pass it the configuration and the translation functions:
@@ -78,13 +80,17 @@ Finally we add an `index.tsx` with some translation:
 _src/routes/index.tsx_
 ```tsx
 import {
-  $translate as t,
-  formatDate as fd,
-  formatNumber as fn,
+  useTranslate,
+  useFormatDate,
+  useFormatNumber,
   Speak,
 } from 'qwik-speak';
 
 export const Home = component$(() => {
+  const t = useTranslate();
+  const fd = useFormatDate();
+  const fn = useFormatNumber();
+
   return (
     <>
       <h1>{t('app.title@@{{name}} demo', { name: 'Qwik Speak' })}</h1>
@@ -108,13 +114,48 @@ export default component$(() => {
     </Speak>
   );
 });
+
+export const head: DocumentHead = {
+  title: 'home.head.title@@Qwik Speak',
+  meta: [{ name: 'description', content: 'home.head.description@@Quick start' }]
+};
 ```
-Here we have used the `Speak` component to add scoped translations to the home page. This means that in addition to the `app` asset that comes with the configuration, the home page will also use the `home` asset. To distinguish them, `app` asset keys start with `app` and home asset keys start with `home`.
+Here we have used the `Speak` component to add scoped translations to the `Home` component:
+- `Home` component will use the `home` asset, in addition to the `app` asset that comes with the configuration
+- `home` asset keys start with `home`
 
 We are also providing default values for each translation: `key@@[default value]`.
 
-> `Speak` component is a `Slot` component: because Qwik renders `Slot` components and direct children in isolation, translations are not immediately available in direct children, and we need to use a component for the `Home` page. It is generally not necessary to use more than one `Speak` component per page
+> `Speak` component is a `Slot` component: because Qwik renders `Slot` components and direct children in isolation, translations are not immediately available in direct children, and we need to use a component for the `Home` page. It is not necessary to use more than one `Speak` component per page
+
+## Head metas
+You may have noticed, that in `index.tsx` we have provided the meta title and description with only the keys. Since the Qwik City `DocumentHead` is out of context, we need to do the translations directly in `router-head.tsx`:
 
+_src/components/router-head/router-head.tsx_
+```tsx
+<title>{t(head.title)}</title>
+
+{head.meta.map((m) => (
+  <meta key={m.key} name={m.name} content={m.name === 'description' ? t(m.content!) : m.content} />
+))}
+```
+
+We can also pass the `lang` attribute in the html tag:
+
+_src/entry.ssr.tsx_
+```typescript
+export default function (opts: RenderToStreamOptions) {
+  return renderToStream(<Root />, {
+    manifest,
+    ...opts,
+    // Use container attributes to set attributes on the html tag
+    containerAttributes: {
+      lang: opts.serverData?.locale || config.defaultLocale.lang,
+      ...opts.containerAttributes,
+    },
+  });
+}
+```
 
 ## Resolve locale
 We can resolve the locale to use in two ways: passing the `locale` parameter to the `QwikSpeakProvider` component, or assigning it to the `locale` handled by Qwik. Create `plugin.ts` in the root of the `src/routes` directory:
@@ -151,9 +192,11 @@ Now we want to change locale. Let's create a `ChangeLocale` component:
 
 _src/components/change-locale.tsx_
 ```tsx
-import { $translate as t, useSpeakConfig, SpeakLocale } from 'qwik-speak';
+import { useTranslate, useSpeakConfig, SpeakLocale } from 'qwik-speak';
 
 export const ChangeLocale = component$(() => {
+  const t = useTranslate();
+
   const config = useSpeakConfig();
 
   const changeLocale$ = $((newLocale: SpeakLocale) => {
@@ -187,7 +230,7 @@ export default component$(() => {
 ```
 In `changeLocale$` we set the locale in a cookie, before reloading the page.
 
-## Extraction: [Qwik Speak Extract](./extract.md)
+## Extraction
 We can now extract the translations and generate the `assets` as json. In `package.json` add the following command to the scripts:
 ```json
 "qwik-speak-extract": "qwik-speak-extract --supportedLangs=en-US,it-IT --assetsPath=i18n"
@@ -203,16 +246,51 @@ i18n/en-US/app.json
 i18n/en-US/home.json
 i18n/it-IT/app.json
 i18n/it-IT/home.json
+translations skipped due to dynamic keys: 2
 extracted keys: 4
 ```
 `app` asset and `home` asset for each language, initialized with the default values we provided.
 
+_translations skipped due to dynamic keys_ are meta title and description keys, because those keys are passed as dynamic parameters. We have to add them manually in a new file that we will call `runtime`:
+
+_i18n/[lang]/runtime.json_
+```json
+{
+  "runtime": {
+    "home": {
+      "head": {
+        "title": "Qwik Speak",
+        "description": "Quick start"
+      }
+    }
+  }
+}
+```
+Update the keys in `DocumentHead` of `index.tsx`:
+```tsx
+export const head: DocumentHead = {
+  title: 'runtime.home.head.title@@Qwik Speak',
+  meta: [{ name: 'description', content: 'runtime.home.head.description@@Quick start' }]
+};
+```
+and add `runtime` asset in Speak config:
+```typescript
+assets: [
+  'app' // Translations shared by the pages
+],
+runtimeAssets: [
+  'runtime' // Translations with dynamic keys or parameters
+]
+```
+
 We can translate the `it-IT` files, and run the app:
 ```shell
 npm start
 ```
 
-## Production: [Qwik Speak Inline Vite plugin](./inline.md)
+See [Qwik Speak Extract](./extract.md) for more details.
+
+## Production
 In production mode, `assets` are loaded only during SSR, and to get the translations on the client as well it is required to inline the translations in chucks sent to the browser.
 
 Add `qwikSpeakInline` Vite plugin in `vite.config.ts`:
@@ -253,10 +331,19 @@ export default function (opts: RenderToStreamOptions) {
   });
 }
 ```
-
 Build the production app in preview mode:
 ```shell
 npm run preview
 ```
+Inspect the `qwik-speak-inline.log` file in root folder:
+
+```
+client: root.tsx
+dynamic key: t(head.title) - skip
+dynamic key: t(m.content) - skip
+```
+It contains the non-inlined dynamic keys that we added in the `runtime.json` file.
 
 > The app will have the same behavior as you saw in dev mode, but now the translations are inlined as you can verify by inspecting the production files, reducing resource usage at runtime
+
+See [Qwik Speak Inline Vite plugin](./inline.md) for more details.

docs/testing.md

@@ -9,13 +9,17 @@ Given the `config` object and a component to test like in [Quick Start](./quick-
 _src/routes/index.tsx_
 ```tsx
 import {
-  $translate as t,
-  formatDate as fd,
-  formatNumber as fn,
+  useTranslate,
+  useFormatDate,
+  useFormatNumber,
   Speak,
 } from 'qwik-speak';
 
 export const Home = component$(() => {
+  const t = useTranslate();
+  const fd = useFormatDate();
+  const fn = useFormatNumber();
+
   return (
     <>
       <h1>{t('app.title@@{{name}} demo', { name: 'Qwik Speak' })}</h1>
@@ -57,7 +61,7 @@ test(`[Home Component]: Should render the component`, async () => {
 });
 ```
 
-Optionally, if you need to test the translated texts in different languages, you have to provide `loadTranslation$` to ensure translations are loaded in test environment and the locale to use:
+Optionally, if you need to test the translated texts in different languages, you have to provide `loadTranslation$` to ensure translations are loaded in test environment, and the locale to use:
 
 ```tsx
 test(`[Home Component]: Should render translated texts in Italian`, async () => {