@sheet-i18n/react 0.4.1 → 0.4.3

package/README.md

@@ -1,57 +1,263 @@
 # @sheet-i18n/react
 
-i18n client logic based on React, part of the `sheet-i18n` ecosystem.
+The **client-side i18n library** subpackage of sheet-i18n.
 
-## Installation
+This package provides tools to handle translations in React applications using context and hooks. It simplifies internationalization workflows by offering functions and components to manage, access, and use locale-specific translation data.
 
-To install this package, use your preferred package manager:
+## ✨ Package Introduction
 
-```bash
-npm install @sheet-i18n/react
-# or
-yarn add @sheet-i18n/react
-# or
-pnpm add @sheet-i18n/react
+- **`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.
+
+## 🚀 Getting Started
+
+### Basic Usage
+
+#### 1. Define Translation Data
+
+Prepare locale JSON files:
+
+```json
+// en.json
+{
+  "header": {
+    "login": "Login",
+    "logout": "Logout"
+  }
+}
+
+// ko.json
+{
+  "header": {
+    "login": "로그인",
+    "logout": "로그아웃"
+  }
+}
+```
+
+#### 2. Initialize i18n Store
+
+this store will be used as a core translations module.
+
+```tsx
+import en from './en.json';
+import ko from './ko.json';
+
+import { I18nStore } from '@sheet-i18n/react';
+
+export const i18nStore = new I18nStore({
+  supportedLocales: ['ko', 'en'],
+  defaultLocale: 'ko',
+  localeSet: {
+    ko,
+    en,
+  },
+});
 ```
 
-## ✨ Features
+#### 3. Create i18n Context
+
+```tsx
+import { i18nStore } from './file-path-of-i18nStore-initiated';
+import { createI18nContext } from '@sheet-i18n/react';
+
+export const { IntlProvider, useTranslation } = createI18nContext(i18nStore);
+```
+
+#### 4. Mount Intl Context Provider in your App
+
+```tsx
+import React from 'react';
+import { IntlProvider } from './i18nContext';
+
+const App = () => {
+  return (
+    <IntlProvider>
+      <YourComponent />
+    </IntlProvider>
+  );
+};
+```
+
+#### 5. Use Translations
+
+```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>
+  );
+};
+```
+
+---
+
+## 📦 API Reference
+
+### `I18nStore`
+
+The `I18nStore` manages type-safe translation states, ensuring consistency across locales.
+
+#### Parameters:
+
+- **`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.
+
+> ⚠️ Caveats:
+>
+> 1. `supportedLocales` must be an array of locale strings.
+> 2. `defaultLocale` must exist in `supportedLocales`.
+> 3. `localeSet` must be an object with keys matching `supportedLocales`.
+
+#### Example:
+
+```tsx
+export const i18nStore = new I18nStore({
+  supportedLocales: ['ko', 'en'],
+  defaultLocale: 'ko',
+  localeSet: {
+    ko,
+    en,
+  },
+});
+
+// Accessing properties
+i18nStore.supportedLocales; // ['ko', 'en']
+i18nStore.defaultLocale; // 'ko'
+```
 
-✅ Combines `@sheet-i18n/react-core` and `@sheet-i18n/react-client` for a comprehensive i18n solution.
+### `createI18nContext`
 
-✅ Provides robust client-side logic for handling translations in React applications.
+Generates React context, including the `IntlProvider` and `useTranslation`.
 
-✅ Fully compatible with the `sheet-i18n` ecosystem.
+#### Parameters:
 
-## 📜 Scripts
+- **`i18nStore`**: Instance of `I18nStore`.
 
-These scripts are available in the package:
+> ⚠️ Caveats:
+>
+> 1. `i18nStore` passed to createI18nContext must be an instance of I18nStore.
+> 2. custom object is not allowed to be passed to createI18nContext.
 
-- **build**: Builds the library using `tsup`.
-- **dev**: Watches for changes and rebuilds during development.
+#### Example:
+
+```tsx
+const { IntlProvider, useTranslation } = createI18nContext(i18nStore);
+```
+
+### `IntlProvider`
+
+A React component 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.
+
+- **`children`**: React children.
+
+#### Example:
+
+```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';
+
+interface LayoutProps {
+  params: {
+    locale: Locale;
+  };
+}
+
+export default function Layout({
+  children,
+  params,
+}: PropsWithChildren<PageProps>) {
+  const { defaultLocale } = i18nStore;
+  const currentLocale = params?.locale ?? defaultLocale;
+
+  return <IntlProvider currentLocale={currentLocale}>{children}</IntlProvider>;
+}
+```
+
+### `useTranslation`
+
+A hook to access translations in your components.
+
+#### Parameters:
+
+- **`sheetTitle`**: The sheet title of the translation group.
+
+#### Example:
+
+```tsx
+const { t } = useTranslation('header');
+const translatedMessage = t('login');
+```
+
+### `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.
+
+#### Parameters:
+
+- key (string): The translation key to retrieve the localized string.
+
+```tsx
+const translatedMessage = t('login'); // login is key
+```
+
+- values (object, optional): An object containing key-value pairs to interpolate into the translation string.
+
+```tsx
+// John Doe shown
+const translatedMessage = t('{username} shown', { username: 'John Doe' });
+```
+
+💡 Note: The values object can contain any type of data, including React components.
+
+```tsx
+// <Username /> shown
+const translatedMessage = t('{username} shown', { username: <Username /> });
+```
 
-## 📦 Exports
+## 🛠 Error Handling
 
-The package provides the following exports:
+Custom error messages help identify misconfigurations:
 
-- **CommonJS**: `./dist/index.js`
-- **ES Module**: `./dist/index.mjs`
+1. **Invalid Params**: Ensure `supportedLocales`, `defaultLocale`, and `localeSet` are correctly provided.
+2. **Missing Default Locale**: The `defaultLocale` must exist in `supportedLocales`.
+3. **Invalid LocaleSet**: Ensure the `localeSet` keys match `supportedLocales`.
 
-## ⚠️ Peer Dependencies
+## 📜 Library Versions 🔢
 
-This package works best when used with compatible React and `sheet-i18n` libraries.
+This package supports the following library versions:
 
-## 🛠️ Development Dependencies
+- **React**: `^19.0.0`
+- **React Intl**: `^7.0.4`
 
-- **@sheet-i18n/typescript-config**: Shared TypeScript configuration presets.
-- **@swc/core**: A fast compiler for JavaScript and TypeScript.
+## 📜 License
 
-## 🔑 Keywords
+This project is licensed under the ISC License.
 
-- `sheet-i18n`
-- `react`
+## 👤 Author
 
-## 👨‍💻 Author
+**devAnderson**  
+[GitHub](https://github.com/chltjdrhd777)  
+[chltjdrhd777@gmail.com](mailto:chltjdrhd777@gmail.com)
 
-- **devAnderson**
-- [GitHub Profile](https://github.com/chltjdrhd777)
-- 📧 [Email](mailto:chltjdrhd777@gmail.com)
+</details>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sheet-i18n/react",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "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.1"
+    "@sheet-i18n/typescript-config": "1.3.2"
   },
   "dependencies": {
-    "@sheet-i18n/react-core": "0.4.1",
-    "@sheet-i18n/react-client": "0.4.1"
+    "@sheet-i18n/react-client": "0.4.3",
+    "@sheet-i18n/react-core": "0.4.2"
   },
   "scripts": {
     "build": "tsup",