This is an automated email from the ASF dual-hosted git repository.
ljmotta pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-kie-tools.git
The following commit(s) were added to refs/heads/main by this push:
new 79c13f57740 kie-issues#3298: Improve README for i18n package (#3299)
79c13f57740 is described below
commit 79c13f577408ff7c9155571c582f16b4be932a87
Author: Kusuma04-dev <[email protected]>
AuthorDate: Wed Oct 15 01:00:07 2025 +0530
kie-issues#3298: Improve README for i18n package (#3299)
Co-authored-by: Kusuma <[email protected]>
---
packages/i18n/README.md | 252 +++++++++++++++++++++++++++--------
packages/i18n/examples/react.md | 2 +
packages/i18n/examples/typescript.md | 7 +
3 files changed, 206 insertions(+), 55 deletions(-)
diff --git a/packages/i18n/README.md b/packages/i18n/README.md
index 5a34cb80b95..c015e9d91d3 100644
--- a/packages/i18n/README.md
+++ b/packages/i18n/README.md
@@ -17,51 +17,64 @@
# Apache KIE Tools i18n
-This package provides a type-safe i18n library for a Typescript project.
+This package provides a type-safe internationalization (i18n) library for
TypeScript projects. It enables you to manage translations in a structured and
type-safe manner.
-## Install
+## Installation
-- `npm install @kie-tools-core/i18n`
+```bash
+npm install @kie-tools-core/i18n
+```
+
+## Package Structure
+
+The library is organized into two main submodules:
+
+### 1. Core Module
-## Usage
+Contains all core functionality, including types and the `I18n` class.
-The library is separated into two submodules:
+```typescript
+import * as I18nCore from "@kie-tools-core/i18n/dist/core";
+```
-- core
- All core functionalities, which includes the types, and the I18n class.
- to use the core:
- `import * as I18nCore from "@kie-tools-core/i18n/dist/core"`
-- react-components
+### 2. React Components Module
- All components and types necessaries to integrate on your React project.
+Provides components and types necessary for React integration.
- to use the React components:
- `import * as I18nReact from "@kie-tools-core/i18n/dist/react-components"`
+```typescript
+import * as I18nReact from "@kie-tools-core/i18n/dist/react-components";
+```
## Examples
-- [Typescript](examples/typescript.md)
-- [React](examples/react.md)
+- [TypeScript Implementation](examples/typescript.md)
+- [React Integration](examples/react.md)
-## Core
+## Core Module
-### Class
+### I18n Class
-The core class `I18n` is under the `core` submodule
"@kie-tools-core/i18n/dist/core".
+The main class for handling internationalization is available in the core
submodule.
-- Constructor
+#### Constructor
-```
-defaults: I18nDefaults<D>
-dictionaries: I18nDictionaries<D>
-initialLocale?: string
+```typescript
+constructor(
+ defaults: I18nDefaults<D>,
+ dictionaries: I18nDictionaries<D>,
+ initialLocale?: string
+)
```
-_If no `initialLocale` is provide the default locale will be used as
`initialLocale`_
+Parameters:
-- Available Methods
+- `defaults`: Default locale and dictionary
+- `dictionaries`: Map of available dictionaries
+- `initialLocale`: (Optional) Initial locale to use. If not provided, the
default locale will be used.
-```
+#### Available Methods
+
+```typescript
// Get the current locale
getLocale(): string
@@ -72,55 +85,184 @@ 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
+
+The type of the default dictionary. It defines the structure of your
translations.
+
+```typescript
+type ReferenceDictionary = {
+ [k: string]: string | DictionaryInterpolation | Array<string | number |
Wrapped<string>> | ReferenceDictionary;
+};
+```
+
+#### TranslatedDictionary<D>
-- `ReferenceDictionary<D>`
- The type of the default dictionary
+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>;
+```
-- `TranslatedDictionary<D>`
- The type of any other dictionary that isn't the default.
+#### When to use ReferenceDictionary vs TranslatedDictionary<D>
-- `I18nDefaults<D>`
- The type of the default configs to be used on the `I18nDictionariesProvider`
component or `I18n` class.
+- **ReferenceDictionary**: Use this for your default/reference language
(typically English). This dictionary must contain all translation keys and
serves as the complete structure for all translations.
-```ts
-interface I18nDefaults<D extends ReferenceDictionary<D>> {
- locale: string; // current locale
- dictionary: D; // default dictionary
+- **TranslatedDictionary<D>**: Use this for all other language dictionaries.
Since it makes all properties optional (via `DeepOptional<D>`), you can provide
partial translations while maintaining type safety against your reference
dictionary.
+
+**Example:**
+
+```typescript
+// Define your reference dictionary structure
+interface MyDictionary extends ReferenceDictionary {
+ title: string;
+ description: string;
}
+
+// Complete reference dictionary (English)
+const en: MyDictionary = {
+ title: "Development only",
+ description: "Description value",
+};
+
+// Partial translation
+const de: TranslatedDictionary<MyDictionary> = {
+ title: "Nur für die Entwicklung",
+ // description key can be omitted and will fall back to the reference
dictionary
+};
```
-- `I18nDictionaries<D>`
- The type of the dictionaries to be used on the `I18nDictionariesProvider`
component or `I18n` class.
+#### I18nDefaults<D>
+
+Configuration type for the default settings.
-```ts
-type I18nDictionaries<D extends ReferenceDictionary<D>> = Map<string,
TranslatedDictionary<D>>;
+```typescript
+interface I18nDefaults<D extends ReferenceDictionary> {
+ locale: string; // Default locale
+ dictionary: D; // Default dictionary
+}
```
-## React
+#### I18nDictionaries<D>
+
+Type for the collection of available dictionaries.
+
+```typescript
+type I18nDictionaries<D extends ReferenceDictionary> = Map<string,
TranslatedDictionary<D>>;
+```
+
+#### 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
+}
+````
+
+## Best Practices
+
+1. **Define a complete reference dictionary**: Create a comprehensive default
dictionary (usually English) that includes all translation keys.
+
+2. **Use type safety**: Leverage TypeScript's type system to catch missing
translations at compile time.
+
+3. **Organize translations logically**: Group related translations together in
nested objects.
+
+4. **Use interpolation functions** for dynamic content:
+
+ ```typescript
+ greeting: (name: string) => `Hello, ${name}!`;
+ ```
+
+5. **Handle pluralization** with appropriate functions:
+ ```typescript
+ itemCount: (count: number) => `${count} ${count === 1 ? "item" : "items"}`;
+ ```
+
---
Apache KIE (incubating) is an effort undergoing incubation at The Apache
Software
diff --git a/packages/i18n/examples/react.md b/packages/i18n/examples/react.md
index 44d267c8b82..03b830b0e30 100644
--- a/packages/i18n/examples/react.md
+++ b/packages/i18n/examples/react.md
@@ -41,6 +41,7 @@ interface MyDictionary extends
ReferenceDictionary<MyDictionary> {
myNestedObject: {
myNestedWord: string;
};
+ wrappedExample: Array<string | Wrapped<"componentName">>;
}
```
@@ -55,6 +56,7 @@ const en: MyDictionary = {
myNestedObject: {
myNestedWord: `My ${"Nested".bold()} word`,
},
+ wrappedExample: [wrapped<"componentName">, "some string value"],
};
```
diff --git a/packages/i18n/examples/typescript.md
b/packages/i18n/examples/typescript.md
index 486e12022a5..8e08e8a2c30 100644
--- a/packages/i18n/examples/typescript.md
+++ b/packages/i18n/examples/typescript.md
@@ -41,6 +41,7 @@ interface MyDictionary extends
ReferenceDictionary<MyDictionary> {
myNestedObject: {
myNestedWord: string;
};
+ wrappedExample: Array<string | Wrapped<"componentName">>;
}
```
@@ -55,6 +56,7 @@ const en: MyDictionary = {
myNestedObject: {
myNestedWord: `My ${"Nested".bold()} word`,
},
+ wrappedExample: [wrapped<"componentName">, "some string value"],
};
```
@@ -97,6 +99,11 @@ function myFunction(myI18n: I18n) {
console.log(i18n.myWord);
}
+
+// Using the custom hook created on ./i18n/locales/index.ts with locale
+function myFunction(myI18n: I18n) {
+ const i18n = myI18n.setLocale(locale).getCurrent();
+}
```
_Remember: If you wish it's possible to use the Context directly with
`MyAppI18nContext.Provider`!_
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
