sheet-i18n 0.2.5-canary.0 → 0.2.5-canary.10

package/README.md

@@ -22,15 +22,15 @@ npm install sheet-i18n
 
 This is the core package for sheet-based translations. You can use it to work with Google Sheets and export translations.
 
-<details open>
-  <summary>📄 Server export function - `sheet-i18n/exporter`</summary>
+<details>
+  <summary>📄 Server export function - sheet-i18n/exporter</summary>
 
 #### `sheet-i18n/exporter`
 
 The **server-side exporter** subpackage allows you to interact with Google Sheets and export translations directly into your project. This is primarily used in server-side environments, such as Next.js API routes or other backend frameworks, where you want to fetch and store translations from a Google Spreadsheet to be served to clients or used within your server application.
 
 ```jsx
-import { googleSheetExporter } from 'sheet-i18n';
+import { googleSheetExporter } from 'sheet-i18n/exporter';
 
 const exporter = await googleSheetExporter({
   credentials: {
@@ -38,7 +38,7 @@ const exporter = await googleSheetExporter({
     clientEmail: 'your-client-email',
     privateKey: 'your-private-key',
   },
-  defaultLocale: 'default-language',
+  defaultLocale: 'default-language-in-sheet-header',
 });
 
 await exporter.exportTranslations();
@@ -136,3 +136,261 @@ This package provides a streamlined way to export data using sheets API. It is d
 The exported translations will be saved in a format that is easy to use for localization purposes. Each translation is stored in its respective locale folder, with a structured format.
 
 </details>
+
+---
+
+<details>
+  <summary>📄 Client export function - sheet-i18n/react</summary>
+
+#### `sheet-i18n/react`
+
+The **client-side i18n library** subpackage.
+
+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.
+
+## ✨ Package Introduction
+
+- **createI18nStore**: `Store Creation` for managing translation data.
+- **createI18nContext**: `React Context` to generate providers and hooks for translations.
+- **IntlProvider**: `Translation Provider` for managing current locale.
+- **useTranslation**: `Translation Hook` for easy access to translation messages.
+
+## 🚀 Getting Started
+
+### Package list
+
+```bash
+import { createI18nStore, createI18nContext, useTranslation } from '@sheet-i18n/react';
+```
+
+### Basic Usage
+
+#### 1. Define Translation Data
+
+Prepare locale JSON files:
+
+```json
+// en.json
+{
+  "header": {
+    "login": "Login",
+    "logout": "Logout"
+  }
+}
+
+// ko.json
+{
+  "header": {
+    "login": "로그인",
+    "logout": "로그아웃"
+  }
+}
+```
+
+#### 2. Create i18n Store
+
+this store will be used as a core translations module.
+
+```tsx
+import en from './en.json';
+import ko from './ko.json';
+
+import { createI18nStore } from '@sheet-i18n/react';
+
+export const i18nStore = createI18nStore({
+  supportedLocales: ['ko', 'en'],
+  defaultLocale: 'ko',
+  localeSet: {
+    ko,
+    en,
+  },
+});
+```
+
+#### 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 = (currentLocale: string) => {
+  return (
+    <IntlProvider currentLocale={currentLocale}>
+      <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
+
+### `createI18nStore`
+
+Creates a store for managing translations.
+
+#### Parameters:
+
+- **`supportedLocales`** (array): Array of supported locale strings in your project.
+- **`defaultLocale`** (string): Default locale to use.
+- **`localeSet`** (object): Object containing translations for each locale.
+
+#### Example:
+
+```tsx
+const i18nStore = createI18nStore({
+  supportedLocales: ['ko', 'en'],
+  defaultLocale: 'ko',
+  localeSet: { ko, en },
+});
+```
+
+---
+
+### `createI18nContext`
+
+Generates React context, including the `IntlProvider` and `useTranslation`.
+
+#### Parameters:
+
+- **`i18nStore`**: Output of `createI18nStore`.
+
+#### Example:
+
+```tsx
+const { IntlProvider, useTranslation } = createI18nContext(i18nStore);
+```
+
+---
+
+### `IntlProvider`
+
+A React component to provide translations to child components.
+
+#### Props:
+
+- **`currentLocale`**: Key locale. This will determine which locale to use for translations data.
+- **`children`**: React children.
+
+#### Example:
+
+```tsx
+<IntlProvider currentLocale="ko">{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 /> });
+> ```
+
+## 🛠 Error Handling
+
+Custom error messages help identify misconfigurations:
+
+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`.
+
+## 🌍 Example Usage in Applications
+
+```tsx
+import { useTranslation } from './i18nContext';
+
+const TableComponent = () => {
+  const { t } = useTranslation('header');
+
+  const columns = [
+    {
+      title: t('logout'),
+      dataIndex: 'action',
+    },
+  ];
+
+  return <Table columns={columns} />;
+};
+```
+
+## 📜 Library Versions 🔢
+
+This package supports the following library versions:
+
+- **React**: `^19.0.0`
+- **React Intl**: `^7.0.4`
+
+## 📜 License
+
+This project is licensed under the ISC License.
+
+## 👤 Author
+
+**devAnderson**  
+[GitHub](https://github.com/chltjdrhd777)  
+[chltjdrhd777@gmail.com](mailto:chltjdrhd777@gmail.com)
+
+</details>

package/dist/exporter/index.d.ts

@@ -0,0 +1 @@
+export * from '@sheet-i18n/exporter';

package/dist/exporter/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/exporter/index.ts
+var exporter_exports = {};
+module.exports = __toCommonJS(exporter_exports);
+__reExport(exporter_exports, require("@sheet-i18n/exporter"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("@sheet-i18n/exporter")
+});

package/dist/exporter/index.mjs

@@ -0,0 +1,2 @@
+// src/exporter/index.ts
+export * from "@sheet-i18n/exporter";

package/dist/index.d.ts

@@ -1 +1,2 @@
-export * from '@sheet-i18n/exporter';
+import '@sheet-i18n/react';
+import '@sheet-i18n/exporter';

package/dist/index.js

@@ -11,14 +11,8 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
 var src_exports = {};
 module.exports = __toCommonJS(src_exports);
-__reExport(src_exports, require("@sheet-i18n/exporter"), module.exports);
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  ...require("@sheet-i18n/exporter")
-});

package/dist/index.mjs

@@ -1,2 +0,0 @@
-// src/index.ts
-export * from "@sheet-i18n/exporter";

package/dist/react/index.d.ts

@@ -0,0 +1 @@
+export * from '@sheet-i18n/react';

package/dist/react/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react/index.ts
+var react_exports = {};
+module.exports = __toCommonJS(react_exports);
+__reExport(react_exports, require("@sheet-i18n/react"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("@sheet-i18n/react")
+});

package/dist/react/index.mjs

@@ -0,0 +1,2 @@
+// src/react/index.ts
+export * from "@sheet-i18n/react";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sheet-i18n",
-  "version": "0.2.5-canary.0",
+  "version": "0.2.5-canary.10",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -8,15 +8,15 @@
     "dist/**/*"
   ],
   "exports": {
-    ".": {
-      "require": "./dist/index.js",
-      "import": "./dist/index.mjs",
-      "types": "./dist/index.d.ts"
-    },
     "./exporter": {
       "require": "./dist/exporter/index.js",
       "import": "./dist/exporter/index.mjs",
       "types": "./dist/exporter/index.d.ts"
+    },
+    "./react": {
+      "require": "./dist/react/index.js",
+      "import": "./dist/react/index.mjs",
+      "types": "./dist/react/index.d.ts"
     }
   },
   "keywords": [
@@ -32,12 +32,13 @@
   },
   "license": "ISC",
   "dependencies": {
-    "@sheet-i18n/exporter": "0.2.1"
+    "@sheet-i18n/exporter": "0.2.2-canary.3",
+    "@sheet-i18n/react": "0.1.1-canary.5"
   },
   "devDependencies": {
     "tsup": "^6.0.0",
     "typescript": "^5.0.0",
-    "@sheet-i18n/typescript-config": "0.2.1"
+    "@sheet-i18n/typescript-config": "0.2.2-canary.3"
   },
   "scripts": {
     "build": "tsup",