@sheet-i18n/react 1.0.2 → 1.0.4

package/README.md

@@ -9,7 +9,8 @@ This package provides tools to handle translations in React applications using c
 - **`I18nStore`**: _Store Creation Class_ for managing translation data.
 - **`createI18nContext`**: _React Context_ to generate providers and hooks for translation.
 - **`IntlProvider`**: _React Translation Provider_ for managing current locale.
-- **`useTranslation`**: _Translation Hook_ for easy access to translation messages.
+- **`useTranslation`**: _Client Side Translation Hook_ for easy access to translation messages on the client side.
+- **`getTranslation`**: _Static Translation Function_ for easy access to translation messages on Static module files.
 
 ## 🚀 Getting Started
 
@@ -37,7 +38,7 @@ Prepare locale JSON files:
 }
 ```
 
-#### 2. Initialize i18n Store
+#### 2. Initialize i18nStore
 
 this store will be used as a core translations module.
 
@@ -63,7 +64,8 @@ export const i18nStore = new I18nStore({
 import { i18nStore } from './file-path-of-i18nStore-initiated';
 import { createI18nContext } from '@sheet-i18n/react';
 
-export const { IntlProvider, useTranslation } = createI18nContext(i18nStore);
+export const { IntlProvider, useTranslation, getTranslation } =
+  createI18nContext(i18nStore);
 ```
 
 #### 4. Mount Intl Context Provider in your App
@@ -99,11 +101,11 @@ const YourComponent = () => {
 };
 ```
 
----
+<br/>
 
-## 📦 API Reference
+## 📦 Base API Reference
 
-### `I18nStore`
+### `I18nStore(core)`
 
 The `I18nStore` manages type-safe translation states, ensuring consistency across locales.
 
@@ -112,6 +114,25 @@ The `I18nStore` manages type-safe translation states, ensuring consistency acros
 - **`supportedLocales`**: Array of supported locale strings.
 - **`defaultLocale`**: The default locale, included in `supportedLocales`.
 - **`localeSet`**: An object where keys match `supportedLocales`, and values are translation sets.
+- **`typeSafe(optional, default = true)`**: An optional boolean indicating whether to use type-safe translations.
+
+> 💡 **typeSafe?** <br/>
+> I18nStore is type-safe by default. So, basically, you can't add the translation data that is not defined in the locale Json files. However, for fast development, you can off the typeSafe option manually.
+>
+> ```tsx
+> // typeSafe: false
+> const YourComponent = () => {
+>   // useTranslation(sheetTitle: string)
+>   const { t } = useTranslation('header');
+>
+>   return (
+>     <div>
+>       {/* t(key: string): any */}
+>       <button>{t('login')}</button>
+>     </div>
+>   );
+> };
+> ```
 
 > ⚠️ Caveats:
 >
@@ -157,15 +178,15 @@ const { IntlProvider, useTranslation } = createI18nContext(i18nStore);
 
 ### `IntlProvider`
 
-A React component to provide translations to child components.
+A Context provider to provide translations to child components.
 
 #### Properties:
 
 - **`currentLocale`** (optional):
 
   - A key representing the current locale to use for translations.
-  - If not provided, the user's preferred language is automatically detected based on their browser settings.
-  - Falls back to the default locale in **i18nStore** if the detected language is unsupported.
+  - If not provided, the user's preferred language is automatically detected based on the browser setting.
+  - The fallback is the default locale in **i18nStore** if the detected language is unsupported.
 
 - **`children`**: React children.
 
@@ -174,9 +195,7 @@ A React component to provide translations to child components.
 ```tsx
 // Add currentLocale if you want to manually handle the locale
 
-// The example is Next.js app routing
-import { i18nStore } from './file-path-of-i18nStore-initiated';
-
+// This example is Next.js app routing
 interface LayoutProps {
   params: {
     locale: Locale;
@@ -206,6 +225,35 @@ const { t } = useTranslation('header');
 const translatedMessage = t('login');
 ```
 
+### `getTranslation`
+
+A hook to access translations in static modules.
+
+#### Parameters:
+
+- **`sheetTitle`**: The sheet title of the translation group.
+
+#### Example:
+
+```tsx
+// data.ts
+import { getTranslation } from './i18nContext';
+
+const { t } = getTranslation('header');
+
+export const STATUS_CATEGORY = [
+  t('Total Energy Usage'),
+  t('Total Waste Usage'),
+];
+
+// App.tsx
+import { STATUS_CATEGORY } from './data';
+
+export default function App() {
+  return STATUS_CATEGORY.map((item) => <div>{item}</div>);
+}
+```
+
 ### `t Function`
 
 The t function is used to retrieve a translation string based on a key and optionally interpolate variables. It provides flexibility to include dynamic values, such as plain strings or React components, for enhanced localization capabilities.
@@ -232,6 +280,85 @@ const translatedMessage = t('{username} shown', { username: 'John Doe' });
 const translatedMessage = t('{username} shown', { username: <Username /> });
 ```
 
+<br/>
+
+## 📄 Best Practices of Translation utilities
+
+A robust and flexible translation library designed for efficient handling of translations in React applications.
+
+### Features
+
+- **Client-Side Translation (Explicit Strings)**: Translate explicit string keys directly in your components.
+- **Client-Side Translation (Dynamic Strings)**: Dynamically match translations from JSON for unknown variables.
+- **Static Module Translation**: Use translations in static modules for configuration constants.
+
+### Usage
+
+#### 1. **Client-Side Translation (Explicit Strings)**
+
+Retrieve translations for explicit keys in your React components using `useTranslation`.
+
+```tsx
+import React from 'react';
+import { useTranslation } from './i18nContext';
+
+const YourComponent = () => {
+  const { t } = useTranslation('header');
+
+  return (
+    <div>
+      <button>{t('login')}</button>
+      <button>{t('logout')}</button>
+    </div>
+  );
+};
+```
+
+#### 2. **Client-Side Translation (Dynamic Strings)**
+
+For scenarios where the string key is not explicitly known (e.g., coming from a server), use `t.dynamic`. Ensure that your translation JSON and sheet are updated to include the variable values.
+</br></br>
+The **t.dynamic** function will automatically match the values from the JSON with the provided arguments and display the result.
+
+```tsx
+// App.tsx
+import { useTranslation } from './i18nContext';
+
+const { t } = useTranslation('header');
+const { data } = useQuery(...queryOptions);
+
+const deviceName = data?.device?.name;
+
+return <div>{t.dynamic(deviceName)}</div>;
+```
+
+#### 3. **Static Module Translation**
+
+Use `getTranslation` to initialize translations for static configurations, constants, or data that needs to be translated.
+
+The **"t"** function from `getTranslation` returns a **Promise** that resolves to the translated string.
+
+> 💡 Note <br/>
+> The **`t`** function returned by **`getTranslation`** resolves its Promise in the background. For display purposes, you don't need to wait for the Promise to resolve, allowing you to use it without async/await.<br/> However, if you need to work with the fulfilled translated value during runtime, you have use async/await to retrieve it.
+
+```tsx
+// data.ts
+import { getTranslation } from './i18nContext';
+const { t } = getTranslation('header');
+
+export const STATUS_CATEGORY = [
+  t('Total Energy Usage'),
+  t('Total Waste Usage'),
+];
+
+// App.tsx
+import { STATUS_CATEGORY } from './data';
+
+export default function App() {
+  return STATUS_CATEGORY.map((item) => <div>{item}</div>);
+}
+```
+
 ## 🛠 Error Handling
 
 Custom error messages help identify misconfigurations:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sheet-i18n/react",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "i18n client logic based on react",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -29,11 +29,11 @@
   "license": "ISC",
   "devDependencies": {
     "@swc/core": "^1.10.2",
-    "@sheet-i18n/typescript-config": "1.3.3"
+    "@sheet-i18n/typescript-config": "1.3.5"
   },
   "dependencies": {
-    "@sheet-i18n/react-core": "1.0.1",
-    "@sheet-i18n/react-client": "1.0.2"
+    "@sheet-i18n/react-core": "1.0.3",
+    "@sheet-i18n/react-client": "1.0.4"
   },
   "scripts": {
     "build": "tsup",