You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kie.apache.org by "Kusuma04-dev (via GitHub)" <gi...@apache.org> on 2025/10/07 07:21:30 UTC

[PR] kie-issues#3298: Improve README for i18n package [incubator-kie-tools]

Kusuma04-dev opened a new pull request, #3299:
URL: https://github.com/apache/incubator-kie-tools/pull/3299

   closes https://github.com/apache/incubator-kie-tools/issues/3298
   
   Improved README for i18n package


-- 
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: commits-unsubscribe@kie.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For additional commands, e-mail: commits-help@kie.apache.org

Re: [PR] kie-issues#3298: Improve README for i18n package [incubator-kie-tools]

Posted by "ljmotta (via GitHub)" <gi...@apache.org>.
ljmotta merged PR #3299:
URL: https://github.com/apache/incubator-kie-tools/pull/3299


-- 
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: commits-unsubscribe@kie.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For additional commands, e-mail: commits-help@kie.apache.org

Re: [PR] kie-issues#3298: Improve README for i18n package [incubator-kie-tools]

Posted by "Copilot (via GitHub)" <gi...@apache.org>.
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: commits-unsubscribe@kie.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For additional commands, e-mail: commits-help@kie.apache.org