diff --git a/docs/en-US/next/api/components/derive.mdx b/docs/en-US/next/api/components/derive.mdx index 674b7bf..93edcf6 100644 --- a/docs/en-US/next/api/components/derive.mdx +++ b/docs/en-US/next/api/components/derive.mdx @@ -2,4 +2,250 @@ title: Derive description: API reference for the Derive component --- -{/* AUTO-GENERATED: Do not edit directly. Edit the template in content/docs-templates/ instead. */} + +## Overview + +The `` component is used to handle sentence fragmentation and reusable content without sacrificing word agreement, conjugation, and word order changes. +In the following example, two separate translations are created: "The beautiful boy plays with the ball" and "The beautiful girl plays with the ball". + +```jsx +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + + + The beautiful {getSubject(gender)} plays with the ball. +; +``` + +The `` component tells the CLI tool to dereference a function call and catalog all possible content being returned by that function, treating every return statement as if it had a `` component wrapping it. + + + **Advanced Usage:** + The `` component is an advanced feature and should be used with caution as it can generate deceptively large numbers of translation entries. + Furthermore, `` enforces a strict requirement that all possible content permutations must be statically analyzable. + + +For more information, see the release notes for [gt-next@6.8.0](/devlog/gt-next_v6_8_0). + +--- + +## Reference + +### Props + + + +### Description + +| Prop | Description | +| ---------- | -------------------------------------------------------------------------------------------------- | +| `children` | Static content. The CLI tool will analyze all possible return values. | + + +### Returns + +`React.JSX.Element` containing the rendered content from the function call, with each possible outcome creating a separate translation entry. + +--- + +## Behavior + +### Build time analysis + +During the build process, the CLI tool analyzes the children of `` components and creates separate translation entries for each possible outcome. +This enables proper grammatical agreement and word order handling across different languages. + +### Requirements + +The children of `` components must be determinable at build time. The supported syntax includes: + +- String, number, and boolean literals +- JSX expressions with nested `` and `` components +- Ternary operators +- Function invocations (that have statically analyzable outcomes) + +--- + +## Examples + +### Basic usage + +Use `` to handle dynamic content that affects sentence structure. + +```jsx title="BasicExample.jsx" copy +import { T, Derive } from 'gt-next'; + +export default function Example({ gender }) { + return ( + + The {gender === 'male' ? 'boy' : 'girl'} is beautiful. + + ); +} +``` + +This creates two translation entries: + +- "The boy is beautiful" +- "The girl is beautiful" + +### With function invocations + +Use `` to handle dynamic content that affects sentence structure from a function invocation. + +```jsx title="BasicExample.jsx" copy +import { T, Derive } from 'gt-next'; + +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + +export default function Example({ gender }) { + return ( + + The {getSubject(gender)} is beautiful. + + ); +} +``` + +### With variables + +Combine `` with `` for dynamic content within static function returns. + +```jsx title="WithVariables.jsx" copy +import { T, Derive, Var } from 'gt-next'; + + +function getTitle(title) { + return title === 'Mr.' ? 'Mr.' : 'Ms.'; +} + +function getGreeting(title) { + return ( + <> + Hello, {getTitle(title)}. How are you, {name}? + + ); +} + +export default function Greeting({ title, name }) { + return ( + + {getGreeting(title)} + + ); +} +``` + +### Multiple Derive components + +Be careful when using multiple `` components as they multiply translation entries. + +```jsx title="MultipleDerive.jsx" copy +import { T, Derive } from 'gt-next'; + +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + +function getObject(toy) { + return toy === 'ball' ? 'ball' : 'crayon'; +} + +export default function PlayExample({ gender, toy }) { + return ( + + {getSubject(gender)} plays with the{' '} + {getObject(toy)}. + + ); +} +``` + +This creates four translation entries (2 × 2 combinations): + +- "boy plays with the ball" +- "boy plays with the crayon" +- "girl plays with the ball" +- "girl plays with the crayon" + +### Supported function syntax + +```jsx title="SupportedSyntax.jsx" copy +function getExamples(key) { + switch (key) { + case 'literals': + if (condition1) { + return 'The boy'; + } else if (condition2) { + return 22; + } else { + return true; + } + case 'jsx': + return ( + <> + Hello, {getTitle(title)}. How are you,{' '} + {name}? + + ); + case 'ternary': + return condition ? 'The boy' : 'The girl'; + case 'function_calls': + return otherStaticFunction(); + } +} +``` + +--- + +## Limitations + +### Performance impact + +Using `` can create exponential growth in translation entries. +Each additional `` component multiplies the total number of translations. + +### Variable content + +Any dynamic or variable content within static function returns must be wrapped in `` components. + +```jsx +// Correct +function getContent() { + return ( + <> + Hello, {userName}! + + ); +} + +// Incorrect - will cause build errors +function getContent() { + return <>Hello, {userName}!; +} +``` + +--- + +## Notes + +- The `` component is designed for handling sentence fragmentation while maintaining grammatical accuracy across languages. +- Always consider the performance implications of multiple `` components in a single translation. +- Treat every return statement in static functions as if wrapped with a `` component. +- Use `` judiciously - prefer simpler translation structures when possible. + +## Next steps + +- For variable content within translations, see the [``](/docs/next/api/components/var) component. +- For the main translation component, see [``](/docs/next/api/components/t). +- For the string equivalent of ``, see [`derive`](/docs/next/api/strings/derive). \ No newline at end of file diff --git a/docs/en-US/next/api/strings/derive.mdx b/docs/en-US/next/api/strings/derive.mdx index 2893bd7..f229e06 100644 --- a/docs/en-US/next/api/strings/derive.mdx +++ b/docs/en-US/next/api/strings/derive.mdx @@ -2,4 +2,205 @@ title: derive description: API reference for the derive() string function --- -{/* AUTO-GENERATED: Do not edit directly. Edit the template in content/docs-templates/ instead. */} + +## Overview + +The `derive` function allows static function calls or variable expressions inside of a string translation. +This is useful for writing reusable code, internationalizing fragmented sentences, and preserving word agreement. + +```jsx +const getDisplayName = (condition) => { + return condition ? "Brian" : 'Archie'; +}; + +gt(`${derive(getDisplayName(condition))} says hello.`); +// Creates two translation entries: +// "Brian says hello." -> "Brian dice hola." +// "Archie says hello." -> "Archie dice hola." +``` + +This works by generating distinct translations for each possible outcome, which has the benefit of preserving word agreement, conjugation, and word order changes across languages. + + +**Multiple Translation Entries:** +`derive` creates separate translation entries for each possible outcome of the wrapped function, which can significantly increase the number of translations. +Use this feature judiciously and prefer ICU select statements when the multiplication factor becomes excessive. + + + +**Static Analysis:** +`derive` can only analyze content that is known at build time. +Any dynamic content (variables, api calls, etc.) must be wrapped with `declareVar`. + + +## Reference +### Parameters + +| Name | Type | Description | +|-----------------------|--|-----------------------------------------------------------------------------| +| `content` | `T extends string \| boolean \| number \| null \| undefined` | A static function call that returns translatable content. | + +### Returns + +Returns `content` of type `T`. + +--- + +## Behavior + +### Build time analysis +During the build process, the CLI tool: +1. Analyzes the function wrapped by `derive` +2. Determines all possible return values from the function (these must be statically analyzable at build time) +3. Creates separate translation entries for each unique outcome + +### Performance considerations +Like ``, `derive` multiplies translation entries. +Each function call with multiple outcomes creates separate translations, and multiple `derive` calls in the same string multiply the total entries exponentially. + +--- + +## Example + +### Reusable content +You can use `derive` to handle fragmented sentences or for reusable content with function calls. + +```jsx copy +import { derive, gt } from 'gt-next'; + +function getSubject() { + return "boy"; +} + +function Component() { + const translation1 = gt(`The ${derive(getSubject())} is playing.`); + const translation2 = gt(`The ${derive(getSubject())} is having fun.`); + const translation3 = gt(`The ${derive(getSubject())} is having a great time.`); + return

{translation1} {translation2} {translation3}

; +} +``` + +### Fragmented sentences + +You can use `derive` to handle fragmented sentences with function calls. + +```jsx copy +import { derive, gt } from 'gt-next'; + +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + +function Component({ gender }) { + const translation = gt(`The ${derive(getSubject(gender))} is playing.`); + return

{translation}

; +} +``` + +### Agreement + +Without `derive`, translating agreement is syntactically heavy. +You have to add a select statement to handle agreement (plurality, gender, etc.). +Then, you must also enumerate each possible outcome. + + +```jsx copy +import { gt } from 'gt-next'; + +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + +function Component({ gender }) { + const translation = gt( + '{gender, select, boy {The boy is playing.} girl {The girl is playing.} other {}}', + { + gender: getSubject(gender) , + }, + ); + return

{translation}

; +} +``` + +With `derive`, agreement becomes trivial. +No select statement is required, nor do you need to specify every outcome. + +```jsx copy +import { derive, declareVar, gt } from 'gt-next'; + +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + +function Component({ gender }) { + const translation = gt(`The ${derive(getSubject(gender))} is playing.`); + return

{translation}

; +} +``` + +By using `derive`, the CLI tool identifies that `getSubject` has two possible outcomes, and creates a translation entry for each outcome. +By doing so, agreement is handled automatically. +- "The boy is playing" -> "*El* niño está jugando" +- "The girl is playing" -> "*La* niña está jugando" + + +### With variables +You can combine `derive` with `declareVar` for dynamic content. + +```jsx copy +import { derive, declareVar, gt } from 'gt-next'; + +function getGreeting(name) { + return name ? `Hello, ${declareVar(name)}` : 'Hello, stranger'; +} + +function Component({ name }) { + const translation = gt(`${derive(getGreeting(name))}! How are you?`); + return

{translation}

; +} +``` + +### Complex functions +Functions can contain multiple conditional branches and return statements. + +```jsx copy +import { derive, gt } from 'gt-next'; + +function getStatusMessage(status, priority) { + if (status === 'complete') { + return priority === 'high' ? 'Urgent task completed' : 'Task completed'; + } else if (status === 'pending') { + return priority === 'high' ? 'Urgent task pending' : 'Task pending'; + } + return 'Task status unknown'; +} + +function Component({ status, priority }) { + const message = gt(`${derive(getStatusMessage(status, priority))}.`); + return

{message}

; +} +``` + +### Inline expressions and logic +You can embed logic directly inside of the `derive` call. + +```jsx copy +import { derive, gt } from 'gt-next'; + +function Component({ gender }) { + const message = gt(`The ${derive(gender === 'male' ? 'boy' : 'girl')} is playing.`); + return

{message}

; +} +``` +--- + +## Notes +* Use `derive` judiciously as it can exponentially increase translation entries +* All possible outcomes must be statically analyzable at build time +* Variables within static functions should be wrapped with `declareVar` + +## Next steps +* See [`declareVar`](/docs/next/api/strings/declare-var) for marking dynamic content within static functions +* See [`decodeVars`](/docs/next/api/strings/decode-vars) for extracting original values from declared variables +* See [``](/docs/next/api/components/derive) for the JSX equivalent +* Read the [release notes](/devlog/gt-next_v6_12_0) for more information \ No newline at end of file diff --git a/docs/en-US/react-native/api/components/derive.mdx b/docs/en-US/react-native/api/components/derive.mdx index 674b7bf..7a63e7a 100644 --- a/docs/en-US/react-native/api/components/derive.mdx +++ b/docs/en-US/react-native/api/components/derive.mdx @@ -2,4 +2,250 @@ title: Derive description: API reference for the Derive component --- -{/* AUTO-GENERATED: Do not edit directly. Edit the template in content/docs-templates/ instead. */} + +## Overview + +The `` component is used to handle sentence fragmentation and reusable content without sacrificing word agreement, conjugation, and word order changes. +In the following example, two separate translations are created: "The beautiful boy plays with the ball" and "The beautiful girl plays with the ball". + +```jsx +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + + + The beautiful {getSubject(gender)} plays with the ball. +; +``` + +The `` component tells the CLI tool to dereference a function call and catalog all possible content being returned by that function, treating every return statement as if it had a `` component wrapping it. + + + **Advanced Usage:** + The `` component is an advanced feature and should be used with caution as it can generate deceptively large numbers of translation entries. + Furthermore, `` enforces a strict requirement that all possible content permutations must be statically analyzable. + + +For more information, see the release notes for [gt-next@6.8.0](/devlog/gt-next_v6_8_0). + +--- + +## Reference + +### Props + + + +### Description + +| Prop | Description | +| ---------- | -------------------------------------------------------------------------------------------------- | +| `children` | Static content. The CLI tool will analyze all possible return values. | + + +### Returns + +`React.JSX.Element` containing the rendered content from the function call, with each possible outcome creating a separate translation entry. + +--- + +## Behavior + +### Build time analysis + +During the build process, the CLI tool analyzes the children of `` components and creates separate translation entries for each possible outcome. +This enables proper grammatical agreement and word order handling across different languages. + +### Requirements + +The children of `` components must be determinable at build time. The supported syntax includes: + +- String, number, and boolean literals +- JSX expressions with nested `` and `` components +- Ternary operators +- Function invocations (that have statically analyzable outcomes) + +--- + +## Examples + +### Basic usage + +Use `` to handle dynamic content that affects sentence structure. + +```jsx title="BasicExample.jsx" copy +import { T, Derive } from 'gt-react-native'; + +export default function Example({ gender }) { + return ( + + The {gender === 'male' ? 'boy' : 'girl'} is beautiful. + + ); +} +``` + +This creates two translation entries: + +- "The boy is beautiful" +- "The girl is beautiful" + +### With function invocations + +Use `` to handle dynamic content that affects sentence structure from a function invocation. + +```jsx title="BasicExample.jsx" copy +import { T, Derive } from 'gt-react-native'; + +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + +export default function Example({ gender }) { + return ( + + The {getSubject(gender)} is beautiful. + + ); +} +``` + +### With variables + +Combine `` with `` for dynamic content within static function returns. + +```jsx title="WithVariables.jsx" copy +import { T, Derive, Var } from 'gt-react-native'; + + +function getTitle(title) { + return title === 'Mr.' ? 'Mr.' : 'Ms.'; +} + +function getGreeting(title) { + return ( + <> + Hello, {getTitle(title)}. How are you, {name}? + + ); +} + +export default function Greeting({ title, name }) { + return ( + + {getGreeting(title)} + + ); +} +``` + +### Multiple Derive components + +Be careful when using multiple `` components as they multiply translation entries. + +```jsx title="MultipleDerive.jsx" copy +import { T, Derive } from 'gt-react-native'; + +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + +function getObject(toy) { + return toy === 'ball' ? 'ball' : 'crayon'; +} + +export default function PlayExample({ gender, toy }) { + return ( + + {getSubject(gender)} plays with the{' '} + {getObject(toy)}. + + ); +} +``` + +This creates four translation entries (2 × 2 combinations): + +- "boy plays with the ball" +- "boy plays with the crayon" +- "girl plays with the ball" +- "girl plays with the crayon" + +### Supported function syntax + +```jsx title="SupportedSyntax.jsx" copy +function getExamples(key) { + switch (key) { + case 'literals': + if (condition1) { + return 'The boy'; + } else if (condition2) { + return 22; + } else { + return true; + } + case 'jsx': + return ( + <> + Hello, {getTitle(title)}. How are you,{' '} + {name}? + + ); + case 'ternary': + return condition ? 'The boy' : 'The girl'; + case 'function_calls': + return otherStaticFunction(); + } +} +``` + +--- + +## Limitations + +### Performance impact + +Using `` can create exponential growth in translation entries. +Each additional `` component multiplies the total number of translations. + +### Variable content + +Any dynamic or variable content within static function returns must be wrapped in `` components. + +```jsx +// Correct +function getContent() { + return ( + <> + Hello, {userName}! + + ); +} + +// Incorrect - will cause build errors +function getContent() { + return <>Hello, {userName}!; +} +``` + +--- + +## Notes + +- The `` component is designed for handling sentence fragmentation while maintaining grammatical accuracy across languages. +- Always consider the performance implications of multiple `` components in a single translation. +- Treat every return statement in static functions as if wrapped with a `` component. +- Use `` judiciously - prefer simpler translation structures when possible. + +## Next steps + +- For variable content within translations, see the [``](/docs/react-native/api/components/var) component. +- For the main translation component, see [``](/docs/react-native/api/components/t). +- For the string equivalent of ``, see [`derive`](/docs/react-native/api/strings/derive). \ No newline at end of file diff --git a/docs/en-US/react-native/api/strings/derive.mdx b/docs/en-US/react-native/api/strings/derive.mdx index 2893bd7..b69af58 100644 --- a/docs/en-US/react-native/api/strings/derive.mdx +++ b/docs/en-US/react-native/api/strings/derive.mdx @@ -2,4 +2,205 @@ title: derive description: API reference for the derive() string function --- -{/* AUTO-GENERATED: Do not edit directly. Edit the template in content/docs-templates/ instead. */} + +## Overview + +The `derive` function allows static function calls or variable expressions inside of a string translation. +This is useful for writing reusable code, internationalizing fragmented sentences, and preserving word agreement. + +```jsx +const getDisplayName = (condition) => { + return condition ? "Brian" : 'Archie'; +}; + +gt(`${derive(getDisplayName(condition))} says hello.`); +// Creates two translation entries: +// "Brian says hello." -> "Brian dice hola." +// "Archie says hello." -> "Archie dice hola." +``` + +This works by generating distinct translations for each possible outcome, which has the benefit of preserving word agreement, conjugation, and word order changes across languages. + + +**Multiple Translation Entries:** +`derive` creates separate translation entries for each possible outcome of the wrapped function, which can significantly increase the number of translations. +Use this feature judiciously and prefer ICU select statements when the multiplication factor becomes excessive. + + + +**Static Analysis:** +`derive` can only analyze content that is known at build time. +Any dynamic content (variables, api calls, etc.) must be wrapped with `declareVar`. + + +## Reference +### Parameters + +| Name | Type | Description | +|-----------------------|--|-----------------------------------------------------------------------------| +| `content` | `T extends string \| boolean \| number \| null \| undefined` | A static function call that returns translatable content. | + +### Returns + +Returns `content` of type `T`. + +--- + +## Behavior + +### Build time analysis +During the build process, the CLI tool: +1. Analyzes the function wrapped by `derive` +2. Determines all possible return values from the function (these must be statically analyzable at build time) +3. Creates separate translation entries for each unique outcome + +### Performance considerations +Like ``, `derive` multiplies translation entries. +Each function call with multiple outcomes creates separate translations, and multiple `derive` calls in the same string multiply the total entries exponentially. + +--- + +## Example + +### Reusable content +You can use `derive` to handle fragmented sentences or for reusable content with function calls. + +```jsx copy +import { derive, gt } from 'gt-react-native'; + +function getSubject() { + return "boy"; +} + +function Component() { + const translation1 = gt(`The ${derive(getSubject())} is playing.`); + const translation2 = gt(`The ${derive(getSubject())} is having fun.`); + const translation3 = gt(`The ${derive(getSubject())} is having a great time.`); + return

{translation1} {translation2} {translation3}

; +} +``` + +### Fragmented sentences + +You can use `derive` to handle fragmented sentences with function calls. + +```jsx copy +import { derive, gt } from 'gt-react-native'; + +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + +function Component({ gender }) { + const translation = gt(`The ${derive(getSubject(gender))} is playing.`); + return

{translation}

; +} +``` + +### Agreement + +Without `derive`, translating agreement is syntactically heavy. +You have to add a select statement to handle agreement (plurality, gender, etc.). +Then, you must also enumerate each possible outcome. + + +```jsx copy +import { gt } from 'gt-react-native'; + +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + +function Component({ gender }) { + const translation = gt( + '{gender, select, boy {The boy is playing.} girl {The girl is playing.} other {}}', + { + gender: getSubject(gender) , + }, + ); + return

{translation}

; +} +``` + +With `derive`, agreement becomes trivial. +No select statement is required, nor do you need to specify every outcome. + +```jsx copy +import { derive, declareVar, gt } from 'gt-react-native'; + +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + +function Component({ gender }) { + const translation = gt(`The ${derive(getSubject(gender))} is playing.`); + return

{translation}

; +} +``` + +By using `derive`, the CLI tool identifies that `getSubject` has two possible outcomes, and creates a translation entry for each outcome. +By doing so, agreement is handled automatically. +- "The boy is playing" -> "*El* niño está jugando" +- "The girl is playing" -> "*La* niña está jugando" + + +### With variables +You can combine `derive` with `declareVar` for dynamic content. + +```jsx copy +import { derive, declareVar, gt } from 'gt-react-native'; + +function getGreeting(name) { + return name ? `Hello, ${declareVar(name)}` : 'Hello, stranger'; +} + +function Component({ name }) { + const translation = gt(`${derive(getGreeting(name))}! How are you?`); + return

{translation}

; +} +``` + +### Complex functions +Functions can contain multiple conditional branches and return statements. + +```jsx copy +import { derive, gt } from 'gt-react-native'; + +function getStatusMessage(status, priority) { + if (status === 'complete') { + return priority === 'high' ? 'Urgent task completed' : 'Task completed'; + } else if (status === 'pending') { + return priority === 'high' ? 'Urgent task pending' : 'Task pending'; + } + return 'Task status unknown'; +} + +function Component({ status, priority }) { + const message = gt(`${derive(getStatusMessage(status, priority))}.`); + return

{message}

; +} +``` + +### Inline expressions and logic +You can embed logic directly inside of the `derive` call. + +```jsx copy +import { derive, gt } from 'gt-react-native'; + +function Component({ gender }) { + const message = gt(`The ${derive(gender === 'male' ? 'boy' : 'girl')} is playing.`); + return

{message}

; +} +``` +--- + +## Notes +* Use `derive` judiciously as it can exponentially increase translation entries +* All possible outcomes must be statically analyzable at build time +* Variables within static functions should be wrapped with `declareVar` + +## Next steps +* See [`declareVar`](/docs/react-native/api/strings/declare-var) for marking dynamic content within static functions +* See [`decodeVars`](/docs/react-native/api/strings/decode-vars) for extracting original values from declared variables +* See [``](/docs/react-native/api/components/derive) for the JSX equivalent +* Read the [release notes](/devlog/gt-next_v6_12_0) for more information \ No newline at end of file diff --git a/docs/en-US/react/api/components/derive.mdx b/docs/en-US/react/api/components/derive.mdx index 674b7bf..1b13528 100644 --- a/docs/en-US/react/api/components/derive.mdx +++ b/docs/en-US/react/api/components/derive.mdx @@ -2,4 +2,250 @@ title: Derive description: API reference for the Derive component --- -{/* AUTO-GENERATED: Do not edit directly. Edit the template in content/docs-templates/ instead. */} + +## Overview + +The `` component is used to handle sentence fragmentation and reusable content without sacrificing word agreement, conjugation, and word order changes. +In the following example, two separate translations are created: "The beautiful boy plays with the ball" and "The beautiful girl plays with the ball". + +```jsx +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + + + The beautiful {getSubject(gender)} plays with the ball. +; +``` + +The `` component tells the CLI tool to dereference a function call and catalog all possible content being returned by that function, treating every return statement as if it had a `` component wrapping it. + + + **Advanced Usage:** + The `` component is an advanced feature and should be used with caution as it can generate deceptively large numbers of translation entries. + Furthermore, `` enforces a strict requirement that all possible content permutations must be statically analyzable. + + +For more information, see the release notes for [gt-next@6.8.0](/devlog/gt-next_v6_8_0). + +--- + +## Reference + +### Props + + + +### Description + +| Prop | Description | +| ---------- | -------------------------------------------------------------------------------------------------- | +| `children` | Static content. The CLI tool will analyze all possible return values. | + + +### Returns + +`React.JSX.Element` containing the rendered content from the function call, with each possible outcome creating a separate translation entry. + +--- + +## Behavior + +### Build time analysis + +During the build process, the CLI tool analyzes the children of `` components and creates separate translation entries for each possible outcome. +This enables proper grammatical agreement and word order handling across different languages. + +### Requirements + +The children of `` components must be determinable at build time. The supported syntax includes: + +- String, number, and boolean literals +- JSX expressions with nested `` and `` components +- Ternary operators +- Function invocations (that have statically analyzable outcomes) + +--- + +## Examples + +### Basic usage + +Use `` to handle dynamic content that affects sentence structure. + +```jsx title="BasicExample.jsx" copy +import { T, Derive } from 'gt-react'; + +export default function Example({ gender }) { + return ( + + The {gender === 'male' ? 'boy' : 'girl'} is beautiful. + + ); +} +``` + +This creates two translation entries: + +- "The boy is beautiful" +- "The girl is beautiful" + +### With function invocations + +Use `` to handle dynamic content that affects sentence structure from a function invocation. + +```jsx title="BasicExample.jsx" copy +import { T, Derive } from 'gt-react'; + +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + +export default function Example({ gender }) { + return ( + + The {getSubject(gender)} is beautiful. + + ); +} +``` + +### With variables + +Combine `` with `` for dynamic content within static function returns. + +```jsx title="WithVariables.jsx" copy +import { T, Derive, Var } from 'gt-react'; + + +function getTitle(title) { + return title === 'Mr.' ? 'Mr.' : 'Ms.'; +} + +function getGreeting(title) { + return ( + <> + Hello, {getTitle(title)}. How are you, {name}? + + ); +} + +export default function Greeting({ title, name }) { + return ( + + {getGreeting(title)} + + ); +} +``` + +### Multiple Derive components + +Be careful when using multiple `` components as they multiply translation entries. + +```jsx title="MultipleDerive.jsx" copy +import { T, Derive } from 'gt-react'; + +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + +function getObject(toy) { + return toy === 'ball' ? 'ball' : 'crayon'; +} + +export default function PlayExample({ gender, toy }) { + return ( + + {getSubject(gender)} plays with the{' '} + {getObject(toy)}. + + ); +} +``` + +This creates four translation entries (2 × 2 combinations): + +- "boy plays with the ball" +- "boy plays with the crayon" +- "girl plays with the ball" +- "girl plays with the crayon" + +### Supported function syntax + +```jsx title="SupportedSyntax.jsx" copy +function getExamples(key) { + switch (key) { + case 'literals': + if (condition1) { + return 'The boy'; + } else if (condition2) { + return 22; + } else { + return true; + } + case 'jsx': + return ( + <> + Hello, {getTitle(title)}. How are you,{' '} + {name}? + + ); + case 'ternary': + return condition ? 'The boy' : 'The girl'; + case 'function_calls': + return otherStaticFunction(); + } +} +``` + +--- + +## Limitations + +### Performance impact + +Using `` can create exponential growth in translation entries. +Each additional `` component multiplies the total number of translations. + +### Variable content + +Any dynamic or variable content within static function returns must be wrapped in `` components. + +```jsx +// Correct +function getContent() { + return ( + <> + Hello, {userName}! + + ); +} + +// Incorrect - will cause build errors +function getContent() { + return <>Hello, {userName}!; +} +``` + +--- + +## Notes + +- The `` component is designed for handling sentence fragmentation while maintaining grammatical accuracy across languages. +- Always consider the performance implications of multiple `` components in a single translation. +- Treat every return statement in static functions as if wrapped with a `` component. +- Use `` judiciously - prefer simpler translation structures when possible. + +## Next steps + +- For variable content within translations, see the [``](/docs/react/api/components/var) component. +- For the main translation component, see [``](/docs/react/api/components/t). +- For the string equivalent of ``, see [`derive`](/docs/react/api/strings/derive). \ No newline at end of file diff --git a/docs/en-US/react/api/strings/derive.mdx b/docs/en-US/react/api/strings/derive.mdx index 2893bd7..1d1d7af 100644 --- a/docs/en-US/react/api/strings/derive.mdx +++ b/docs/en-US/react/api/strings/derive.mdx @@ -2,4 +2,205 @@ title: derive description: API reference for the derive() string function --- -{/* AUTO-GENERATED: Do not edit directly. Edit the template in content/docs-templates/ instead. */} + +## Overview + +The `derive` function allows static function calls or variable expressions inside of a string translation. +This is useful for writing reusable code, internationalizing fragmented sentences, and preserving word agreement. + +```jsx +const getDisplayName = (condition) => { + return condition ? "Brian" : 'Archie'; +}; + +gt(`${derive(getDisplayName(condition))} says hello.`); +// Creates two translation entries: +// "Brian says hello." -> "Brian dice hola." +// "Archie says hello." -> "Archie dice hola." +``` + +This works by generating distinct translations for each possible outcome, which has the benefit of preserving word agreement, conjugation, and word order changes across languages. + + +**Multiple Translation Entries:** +`derive` creates separate translation entries for each possible outcome of the wrapped function, which can significantly increase the number of translations. +Use this feature judiciously and prefer ICU select statements when the multiplication factor becomes excessive. + + + +**Static Analysis:** +`derive` can only analyze content that is known at build time. +Any dynamic content (variables, api calls, etc.) must be wrapped with `declareVar`. + + +## Reference +### Parameters + +| Name | Type | Description | +|-----------------------|--|-----------------------------------------------------------------------------| +| `content` | `T extends string \| boolean \| number \| null \| undefined` | A static function call that returns translatable content. | + +### Returns + +Returns `content` of type `T`. + +--- + +## Behavior + +### Build time analysis +During the build process, the CLI tool: +1. Analyzes the function wrapped by `derive` +2. Determines all possible return values from the function (these must be statically analyzable at build time) +3. Creates separate translation entries for each unique outcome + +### Performance considerations +Like ``, `derive` multiplies translation entries. +Each function call with multiple outcomes creates separate translations, and multiple `derive` calls in the same string multiply the total entries exponentially. + +--- + +## Example + +### Reusable content +You can use `derive` to handle fragmented sentences or for reusable content with function calls. + +```jsx copy +import { derive, gt } from 'gt-react'; + +function getSubject() { + return "boy"; +} + +function Component() { + const translation1 = gt(`The ${derive(getSubject())} is playing.`); + const translation2 = gt(`The ${derive(getSubject())} is having fun.`); + const translation3 = gt(`The ${derive(getSubject())} is having a great time.`); + return

{translation1} {translation2} {translation3}

; +} +``` + +### Fragmented sentences + +You can use `derive` to handle fragmented sentences with function calls. + +```jsx copy +import { derive, gt } from 'gt-react'; + +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + +function Component({ gender }) { + const translation = gt(`The ${derive(getSubject(gender))} is playing.`); + return

{translation}

; +} +``` + +### Agreement + +Without `derive`, translating agreement is syntactically heavy. +You have to add a select statement to handle agreement (plurality, gender, etc.). +Then, you must also enumerate each possible outcome. + + +```jsx copy +import { gt } from 'gt-react'; + +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + +function Component({ gender }) { + const translation = gt( + '{gender, select, boy {The boy is playing.} girl {The girl is playing.} other {}}', + { + gender: getSubject(gender) , + }, + ); + return

{translation}

; +} +``` + +With `derive`, agreement becomes trivial. +No select statement is required, nor do you need to specify every outcome. + +```jsx copy +import { derive, declareVar, gt } from 'gt-react'; + +function getSubject(gender) { + return gender === 'male' ? 'boy' : 'girl'; +} + +function Component({ gender }) { + const translation = gt(`The ${derive(getSubject(gender))} is playing.`); + return

{translation}

; +} +``` + +By using `derive`, the CLI tool identifies that `getSubject` has two possible outcomes, and creates a translation entry for each outcome. +By doing so, agreement is handled automatically. +- "The boy is playing" -> "*El* niño está jugando" +- "The girl is playing" -> "*La* niña está jugando" + + +### With variables +You can combine `derive` with `declareVar` for dynamic content. + +```jsx copy +import { derive, declareVar, gt } from 'gt-react'; + +function getGreeting(name) { + return name ? `Hello, ${declareVar(name)}` : 'Hello, stranger'; +} + +function Component({ name }) { + const translation = gt(`${derive(getGreeting(name))}! How are you?`); + return

{translation}

; +} +``` + +### Complex functions +Functions can contain multiple conditional branches and return statements. + +```jsx copy +import { derive, gt } from 'gt-react'; + +function getStatusMessage(status, priority) { + if (status === 'complete') { + return priority === 'high' ? 'Urgent task completed' : 'Task completed'; + } else if (status === 'pending') { + return priority === 'high' ? 'Urgent task pending' : 'Task pending'; + } + return 'Task status unknown'; +} + +function Component({ status, priority }) { + const message = gt(`${derive(getStatusMessage(status, priority))}.`); + return

{message}

; +} +``` + +### Inline expressions and logic +You can embed logic directly inside of the `derive` call. + +```jsx copy +import { derive, gt } from 'gt-react'; + +function Component({ gender }) { + const message = gt(`The ${derive(gender === 'male' ? 'boy' : 'girl')} is playing.`); + return

{message}

; +} +``` +--- + +## Notes +* Use `derive` judiciously as it can exponentially increase translation entries +* All possible outcomes must be statically analyzable at build time +* Variables within static functions should be wrapped with `declareVar` + +## Next steps +* See [`declareVar`](/docs/react/api/strings/declare-var) for marking dynamic content within static functions +* See [`decodeVars`](/docs/react/api/strings/decode-vars) for extracting original values from declared variables +* See [``](/docs/react/api/components/derive) for the JSX equivalent +* Read the [release notes](/devlog/gt-next_v6_12_0) for more information \ No newline at end of file