Copilot commented on code in PR #3299:
URL:
https://github.com/apache/incubator-kie-tools/pull/3299#discussion_r2410020944
##########
packages/i18n/README.md:
##########
@@ -72,55 +85,156 @@ getCurrent(): D
setLocale(locale: string): void
```
-### Types
+**Example:**
+
+```typescript
+// Get the current locale
+const locale = i18n.getLocale();
+
+// Get the current dictionary
+const dictionary = i18n.getCurrent();
+
+// Set locale and get current dictionary in one chain
+const dictionary = i18n.setLocale(locale).getCurrent();
+```
+
+### Core Types
-- `ReferenceDictionary<D>`
- The type of the default dictionary
+#### ReferenceDictionary
-- `TranslatedDictionary<D>`
- The type of any other dictionary that isn't the default.
+The type of the default dictionary. It defines the structure of your
translations.
-- `I18nDefaults<D>`
- The type of the default configs to be used on the `I18nDictionariesProvider`
component or `I18n` class.
+```typescript
+type ReferenceDictionary = {
+ [k: string]: string | DictionaryInterpolation | Array<string | number |
Wrapped<string>> | ReferenceDictionary;
+};
+```
-```ts
-interface I18nDefaults<D extends ReferenceDictionary<D>> {
- locale: string; // current locale
- dictionary: D; // default dictionary
+#### TranslatedDictionary<D>
+
+The type for any dictionary that isn't the default one. All properties are
optional, allowing partial translations.
+
+```typescript
+type TranslatedDictionary<D extends ReferenceDictionary> = DeepOptional<D>;
+```
+
+#### I18nDefaults<D>
+
+Configuration type for the default settings.
+
+```typescript
+interface I18nDefaults<D extends ReferenceDictionary> {
+ locale: string; // Default locale
+ dictionary: D; // Default dictionary
}
```
-- `I18nDictionaries<D>`
- The type of the dictionaries to be used on the `I18nDictionariesProvider`
component or `I18n` class.
+#### I18nDictionaries<D>
-```ts
-type I18nDictionaries<D extends ReferenceDictionary<D>> = Map<string,
TranslatedDictionary<D>>;
+Type for the collection of available dictionaries.
+
+```typescript
+type I18nDictionaries<D extends ReferenceDictionary> = Map<string,
TranslatedDictionary<D>>;
```
-## React
+#### DictionaryInterpolation
+
+Function type for dynamic string interpolation.
+
+```typescript
+type DictionaryInterpolation = (...args: Array<string | number>) => string;
+```
+
+## React Integration
### Components
-- `<I18nDictionariesProvider>`
- Provides your implementation of `I18nContextType`
+#### I18nDictionariesProvider
-- `<I18nHtml>` Renders a string with HTML tags
+Provides your implementation of `I18nContextType` to your React component tree.
-_Be aware: the `<I18nHtml>` component uses the `dangerouslySetInnerHTML` prop._
+```tsx
+import { I18nDictionariesProvider } from
"@kie-tools-core/i18n/dist/react-components";
-### Types
+<I18nDictionariesProvider
+ defaults={{ locale: "en", dictionary: enDictionary }}
+ dictionaries={new Map([["pt-BR", ptBrDictionary]])}
+ ctx={MyAppI18nContext}
+>
+ <App />
+</I18nDictionariesProvider>;
+```
-- `I18nContextType<D>`
- The context type use by `<I18nDictionaryProvider>`, provides an object with
the following properties:
+#### I18nHtml
-```ts
-interface I18nContextType<D extends ReferenceDictionary<D>> {
- locale: string; // current locale
- setLocale: React.Dispatch<string>; // a function to set the desired locale
- i18n: D; // Dictionary
-}
+Renders a string containing HTML tags.
+
+```tsx
+<I18nHtml>{i18n.someHtmlContent}</I18nHtml>
```
+**Note:** This component uses React's `dangerouslySetInnerHTML` prop. Ensure
your HTML content is safe to prevent XSS vulnerabilities.
+
+#### I18nWrapped
+
+React component wrapper that enables dynamic content replacement with
localized versions based on keys in a provided components object.
+
Review Comment:
Incorrect markdown code fence - should use three backticks instead of four.
##########
packages/i18n/README.md:
##########
@@ -72,55 +85,156 @@ getCurrent(): D
setLocale(locale: string): void
```
-### Types
+**Example:**
+
+```typescript
+// Get the current locale
+const locale = i18n.getLocale();
+
+// Get the current dictionary
+const dictionary = i18n.getCurrent();
+
+// Set locale and get current dictionary in one chain
+const dictionary = i18n.setLocale(locale).getCurrent();
+```
+
+### Core Types
-- `ReferenceDictionary<D>`
- The type of the default dictionary
+#### ReferenceDictionary
-- `TranslatedDictionary<D>`
- The type of any other dictionary that isn't the default.
+The type of the default dictionary. It defines the structure of your
translations.
Review Comment:
[nitpick] The documentation explains what ReferenceDictionary is but doesn't
clearly explain when to use it vs TranslatedDictionary. Consider adding a brief
comparison or use case example.
##########
packages/i18n/README.md:
##########
@@ -72,55 +85,156 @@ getCurrent(): D
setLocale(locale: string): void
```
-### Types
+**Example:**
+
+```typescript
+// Get the current locale
+const locale = i18n.getLocale();
+
+// Get the current dictionary
+const dictionary = i18n.getCurrent();
+
+// Set locale and get current dictionary in one chain
+const dictionary = i18n.setLocale(locale).getCurrent();
+```
+
+### Core Types
-- `ReferenceDictionary<D>`
- The type of the default dictionary
+#### ReferenceDictionary
-- `TranslatedDictionary<D>`
- The type of any other dictionary that isn't the default.
+The type of the default dictionary. It defines the structure of your
translations.
-- `I18nDefaults<D>`
- The type of the default configs to be used on the `I18nDictionariesProvider`
component or `I18n` class.
+```typescript
+type ReferenceDictionary = {
+ [k: string]: string | DictionaryInterpolation | Array<string | number |
Wrapped<string>> | ReferenceDictionary;
+};
+```
-```ts
-interface I18nDefaults<D extends ReferenceDictionary<D>> {
- locale: string; // current locale
- dictionary: D; // default dictionary
+#### TranslatedDictionary<D>
+
+The type for any dictionary that isn't the default one. All properties are
optional, allowing partial translations.
+
+```typescript
+type TranslatedDictionary<D extends ReferenceDictionary> = DeepOptional<D>;
+```
+
+#### I18nDefaults<D>
+
+Configuration type for the default settings.
+
+```typescript
+interface I18nDefaults<D extends ReferenceDictionary> {
+ locale: string; // Default locale
+ dictionary: D; // Default dictionary
}
```
-- `I18nDictionaries<D>`
- The type of the dictionaries to be used on the `I18nDictionariesProvider`
component or `I18n` class.
+#### I18nDictionaries<D>
-```ts
-type I18nDictionaries<D extends ReferenceDictionary<D>> = Map<string,
TranslatedDictionary<D>>;
+Type for the collection of available dictionaries.
+
+```typescript
+type I18nDictionaries<D extends ReferenceDictionary> = Map<string,
TranslatedDictionary<D>>;
```
-## React
+#### DictionaryInterpolation
+
+Function type for dynamic string interpolation.
+
+```typescript
+type DictionaryInterpolation = (...args: Array<string | number>) => string;
+```
+
+## React Integration
### Components
-- `<I18nDictionariesProvider>`
- Provides your implementation of `I18nContextType`
+#### I18nDictionariesProvider
-- `<I18nHtml>` Renders a string with HTML tags
+Provides your implementation of `I18nContextType` to your React component tree.
-_Be aware: the `<I18nHtml>` component uses the `dangerouslySetInnerHTML` prop._
+```tsx
+import { I18nDictionariesProvider } from
"@kie-tools-core/i18n/dist/react-components";
-### Types
+<I18nDictionariesProvider
+ defaults={{ locale: "en", dictionary: enDictionary }}
+ dictionaries={new Map([["pt-BR", ptBrDictionary]])}
+ ctx={MyAppI18nContext}
+>
+ <App />
+</I18nDictionariesProvider>;
+```
-- `I18nContextType<D>`
- The context type use by `<I18nDictionaryProvider>`, provides an object with
the following properties:
+#### I18nHtml
-```ts
-interface I18nContextType<D extends ReferenceDictionary<D>> {
- locale: string; // current locale
- setLocale: React.Dispatch<string>; // a function to set the desired locale
- i18n: D; // Dictionary
-}
+Renders a string containing HTML tags.
+
+```tsx
+<I18nHtml>{i18n.someHtmlContent}</I18nHtml>
```
+**Note:** This component uses React's `dangerouslySetInnerHTML` prop. Ensure
your HTML content is safe to prevent XSS vulnerabilities.
+
+#### I18nWrapped
+
+React component wrapper that enables dynamic content replacement with
localized versions based on keys in a provided components object.
+
+````tsx
+import { I18nWrapped } from "@kie-tools-core/i18n/dist/react-components";
+import { wrapped } from "@kie-tools-core/i18n/dist/core";
+
+// Define in your dictionary interface
+interface MyDictionary extends ReferenceDictionary<MyDictionary> {
+ message: Array<string | Wrapped<"nameOfTheComponent">>;
+}
+
+// Use in your dictionary
+const en: MyDictionary = {
+ message: [wrapped<"nameOfTheComponent">, "some string value"]
+};
+
+// Use in your component
+<I18nWrapped
+ components={{
+ nameOfTheComponent: <YourComponent />
+ }}
+>
+ {i18n.message}
+</I18nWrapped>
+
+### React Types
+
+#### I18nContextType<D>
+
+The context type used by `I18nDictionaryProvider`.
+
+```typescript
+interface I18nContextType<D extends ReferenceDictionary> {
+ locale: string; // Current locale
+ setLocale: React.Dispatch<string>; // Function to change locale
+ i18n: D; // Current dictionary
+}
+````
Review Comment:
Incorrect markdown code fence - should use three backticks instead of four.
```suggestion
```
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
