Docs: Component$ props

robisim74 · Jun 1, 2023 · 2079450 · 2079450
1 parent db511db
commit 2079450
Show file tree

Hide file tree

Showing 4 changed files with 69 additions and 48 deletions.
diff --git a/docs/translate.md b/docs/translate.md
@@ -7,22 +7,10 @@ const t = useTranslate();
 
 t('home.title@@Qwik Speak')
 ```
-- In dev mode, the function returns the default value (value after `@@`) if provided
-- When extracting translations, it creates scoped translation files:
-
-  _home.json_
-  ```json
-  {
-    "home": {
-      "title": "Qwik Speak"
-    }
-  }
-  ```
-- After extraction, it returns the value in files
-- In prod mod, using _Qwik Speak Inline_ Vite plugin, `t` function is replaced by its translation in chunks sent to the browser:
-  ```tsx
-  `Qwik Speak`
-  ```
+Value after `@@` is the optional default value:
+```tsx
+`Qwik Speak`
+```
 
 ### Params interpolation
 `t` function accept params as well:
@@ -45,7 +33,7 @@ and returns an array of translated values:
 ```
 
 ### Arrays and objects as values
-It can get arrays and objects directly from files:
+`t` function can get arrays and objects directly from files:
 ```json
 {
   "home": {
@@ -55,8 +43,8 @@ It can get arrays and objects directly from files:
       "three"
     ],
     "obj": {
-      "one": "1",
-      "two": "2"
+      "one": "one",
+      "two": "two"
     }
   }
 }
@@ -75,8 +63,41 @@ t('home.array.2@@three')
 Finally, it is possible to set arrays and objects passing a _valid stringified_ default value:
 ```tsx
 t<string[]>('home.array@@["one","two","three"]')
-t<Translation>('home.obj@@{"one":"1","two":"2"}')
+t<Translation>('home.obj@@{"one":"one","two":"two"}')
+```
+
+### Component$ props
+Prefer translating inside components rather than on boundaries:
+
+```tsx
+export const Title = component$<TitleProps>((props) => {
+  return (<h1>{props.name}</h1>)
+});
+
+export const Home = component$(() => {
+  const t = useTranslate();
+
+  const name = t('app.title');
+  return (
+    <Title name={name} />
+  );
+});
+```
+or
+```tsx
+export const Title = component$<TitleProps>((props) => {
+  const t = useTranslate();
+
+  return (<h1>{t(props.name)}</h1>)
+});
+
+export const Home = component$(() => {
+  return (
+    <Title name='app.title' />
+  );
+});
 ```
+In the latter case, `app.title` will have to be placed in the `runtimeAssets`, as a dynamic key is passed to the `t` function.
 
 ## inlineTranslate
 `inlineTranslate` function has the same behavior as the function returned by `useTranslate`, but can be used outside the `component$`, for example in _Inline components_, passing the Speak context as second argument:

diff --git a/packages/qwik-speak/src/tests/config.ts b/packages/qwik-speak/src/tests/config.ts
@@ -22,8 +22,8 @@ export const loadTranslationStub$: LoadTranslationFn = $(() => {
     one: 'One {{ role }} developer',
     other: '{{value}} {{ role }} developers',
     arrayObjects: [
-      { num: '1 {{ param }}' },
-      { num: '3 {{ param }}' }
+      { num: 'one {{ param }}' },
+      { num: 'two {{ param }}' }
     ]
   };
 });

diff --git a/packages/qwik-speak/src/tests/use-translate.test.tsx b/packages/qwik-speak/src/tests/use-translate.test.tsx
@@ -99,8 +99,8 @@ describe('useTranslate function', async () => {
     expect((screen.querySelector('#A10') as HTMLDivElement).innerHTML).toContain('Test');
   });
   test('array of objects', () => {
-    expect((screen.querySelector('#A11') as HTMLDivElement).innerHTML).toContain('1 params');
-    expect((screen.querySelector('#A11') as HTMLDivElement).innerHTML).toContain('3 params');
+    expect((screen.querySelector('#A11') as HTMLDivElement).innerHTML).toContain('one params');
+    expect((screen.querySelector('#A11') as HTMLDivElement).innerHTML).toContain('two params');
   });
   test('conditional rendering', () => {
     expect((screen.querySelector('#A12') as HTMLDivElement).innerHTML).toContain('Test');

diff --git a/packages/qwik-speak/tools/tests/mock.ts b/packages/qwik-speak/tools/tests/mock.ts
@@ -42,8 +42,8 @@ export const Home = component$(() => {
   const tParam = t('home.greeting', { name: t('app.title') });
   const tArray = t<string[]>('home.array@@["{{ name }} one", "{{ name }} two"]', { name: 'n.' });
   const item = t('home.array.2@@{{ name }} three', { name: 'n.' });
-  const tObject = t<Translation>('home.obj@@{"one": "{{ name }} 1", "two": "{{ name }} 2"}', { name: 'n.' });
-  const tArrayObjects = t<Translation[]>('home.arrayObjects@@[{"num": "1"}, {"num": "2"}]');
+  const tObject = t<Translation>('home.obj@@{"one": "{{ name }} one", "two": "{{ name }} two"}', { name: 'n.' });
+  const tArrayObjects = t<Translation[]>('home.arrayObjects@@[{"num": "one"}, {"num": "two"}]');
   console.log(tParam);
   tArray.map((x) => console.log(x));
   console.log(item);
@@ -123,8 +123,8 @@ export const s_dYGb4b0cyCA = ()=>{
     });
     const tArray = t('home.array@@["{{ name }} one", "{{ name }} two"]', { name: 'n.' });
     const item = t('home.array.2@@{{ name }} three', { name: 'n.' });
-    const tObject = t('home.obj@@{"one": "{{ name }} 1", "two": "{{ name }} 2"}', { name: 'n.' });
-    const tArrayObjects = t('home.arrayObjects@@[{"num": "1"}, {"num": "2"}]');
+    const tObject = t('home.obj@@{"one": "{{ name }} one", "two": "{{ name }} two"}', { name: 'n.' });
+    const tArrayObjects = t('home.arrayObjects@@[{"num": "one"}, {"num": "two"}]');
     console.log(tParam);
     tArray.map((x)=>console.log(x));
     console.log(item);
@@ -216,8 +216,8 @@ export const s_dYGb4b0cyCA = ()=>{
     });
     const tArray = __qsInline('home.array@@["{{ name }} one", "{{ name }} two"]', { name: 'n.' });
     const item = __qsInline('home.array.2@@{{ name }} three', { name: 'n.' });
-    const tObject = __qsInline('home.obj@@{"one": "{{ name }} 1", "two": "{{ name }} 2"}', { name: 'n.' });
-    const tArrayObjects = __qsInline('home.arrayObjects@@[{"num": "1"}, {"num": "2"}]');
+    const tObject = __qsInline('home.obj@@{"one": "{{ name }} one", "two": "{{ name }} two"}', { name: 'n.' });
+    const tArrayObjects = __qsInline('home.arrayObjects@@[{"num": "one"}, {"num": "two"}]');
     console.log(tParam);
     tArray.map((x)=>console.log(x));
     console.log(item);
@@ -294,8 +294,8 @@ export const mockChunkCode = `const s_dYGb4b0cyCA = () => {
   });
   const tArray = __qsInline('home.array@@["{{ name }} one", "{{ name }} two"]', { name: 'n.' });
   const item = __qsInline('home.array.2@@{{ name }} three', { name: 'n.' });
-  const tObject = __qsInline('home.obj@@{"one": "{{ name }} 1", "two": "{{ name }} 2"}', { name: 'n.' });
-  const tArrayObjects = __qsInline('home.arrayObjects@@[{"num": "1"}, {"num": "2"}]');
+  const tObject = __qsInline('home.obj@@{"one": "{{ name }} one", "two": "{{ name }} two"}', { name: 'n.' });
+  const tArrayObjects = __qsInline('home.arrayObjects@@[{"num": "one"}, {"num": "two"}]');
   console.log(tParam);
   tArray.map((x) => console.log(x));
   console.log(item);
@@ -370,8 +370,8 @@ export const mockInlinedCode = `const s_dYGb4b0cyCA = () => {
   const tParam = \`Hi! I am \${\`\`}\`;
   const tArray = [\`n. one\`,\`n. two\`,\`n. three\`];
   const item = \`n. three\`;
-  const tObject = {"one":\`n. 1\`,"two":\`n. 2\`};
-  const tArrayObjects = [{"num":"1"},{"num":"2"}];
+  const tObject = {"one":\`n. one\`,"two":\`n. two\`};
+  const tArrayObjects = [{"num":"one"},{"num":"two"}];
   console.log(tParam);
   tArray.map((x) => console.log(x));
   console.log(item);
@@ -444,8 +444,8 @@ export const mockInlinedCodeByLang = `const s_dYGb4b0cyCA = () => {
   const tParam = \`Ciao! Sono \${\`\`}\`;
   const tArray = [\`n. uno\`,\`n. due\`,\`n. tre\`];
   const item = \`n. tre\`;
-  const tObject = {"one":\`n. 1\`,"two":\`n. 2\`};
-  const tArrayObjects = [{"num":"1"},{"num":"2"}];
+  const tObject = {"one":\`n. uno\`,"two":\`n. due\`};
+  const tArrayObjects = [{"num":"uno"},{"num":"due"}];
   console.log(tParam);
   tArray.map((x) => console.log(x));
   console.log(item);
@@ -527,10 +527,10 @@ export const mockExtractedAsset = JSON.stringify({
     ],
     "arrayObjects": [
       {
-        "num": "1"
+        "num": "one"
       },
       {
-        "num": "2"
+        "num": "two"
       }
     ],
     "dates": "Dates & relative time",
@@ -542,8 +542,8 @@ export const mockExtractedAsset = JSON.stringify({
     "increment": "Increment",
     "numbers": "Numbers & currencies",
     "obj": {
-      "one": "{{ name }} 1",
-      "two": "{{ name }} 2"
+      "one": "{{ name }} one",
+      "two": "{{ name }} two"
     },
     "params": "",
     "plural": "Plural",
@@ -561,10 +561,10 @@ export const mockTranslatedAsset = JSON.stringify({
     ],
     "arrayObjects": [
       {
-        "num": "1"
+        "num": "one"
       },
       {
-        "num": "2"
+        "num": "two"
       }
     ],
     "dates": "Dates & relative time",
@@ -576,8 +576,8 @@ export const mockTranslatedAsset = JSON.stringify({
     "increment": "Increment",
     "numbers": "Numbers & currencies",
     "obj": {
-      "one": "{{ name }} 1",
-      "two": "{{ name }} 2"
+      "one": "{{ name }} one",
+      "two": "{{ name }} two"
     },
     "params": "Parameters",
     "plural": "Plural",
@@ -595,10 +595,10 @@ export const mockTranslatedAssetByLang = JSON.stringify({
     ],
     "arrayObjects": [
       {
-        "num": "1"
+        "num": "uno"
       },
       {
-        "num": "2"
+        "num": "due"
       }
     ],
     "dates": "Date e tempo relativo",
@@ -610,8 +610,8 @@ export const mockTranslatedAssetByLang = JSON.stringify({
     "increment": "Incrementa",
     "numbers": "Numeri e valute",
     "obj": {
-      "one": "{{ name }} 1",
-      "two": "{{ name }} 2"
+      "one": "{{ name }} uno",
+      "two": "{{ name }} due"
     },
     "params": "Parametri",
     "plural": "Plurale",