koto-react 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Koto Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# Koto React
+
+> **Koto** (言) — Japanese for "word." Every translation starts with a single word. Koto bridges languages one word at a time.
+
+A React translation library with IndexedDB caching for optimal performance.
+
+## Installation
+
+```bash
+npm install koto-react
+# or
+yarn add koto-react
+```
+
+## Usage
+
+### Basic Setup with Provider
+
+```tsx
+import React from 'react';
+import { HermesProvider } from 'koto-react';
+
+function App() {
+  return (
+    <HermesProvider 
+      apiKey="your-api-key" 
+      defaultLocale="en"
+      apiUrl="https://your-api-endpoint.com/translations" // optional
+    >
+      <YourApp />
+    </HermesProvider>
+  );
+}
+```
+
+### Using the Translation Hook
+
+```tsx
+import React from 'react';
+import { useTranslation } from 'koto-react';
+
+function MyComponent() {
+  const { t, locale, loading } = useTranslation();
+
+  if (loading) {
+    return <div>Loading translations...</div>;
+  }
+
+  return (
+    <div>
+      <h1>{t('checkout.payment.title')}</h1>
+      <p>{t('checkout.payment.description', 'Default fallback text')}</p>
+      <p>Current locale: {locale}</p>
+    </div>
+  );
+}
+```
+
+### Using the Standalone Translation Function
+
+For non-React contexts or utility functions:
+
+```typescript
+import { t, initTranslations } from 'koto-react';
+
+// Initialize once in your app
+await initTranslations('en');
+
+// Use anywhere
+const title = t('checkout.payment.title');
+const notFound = t('some.missing.key'); // Returns 'some.missing.key'
+const withFallback = t('some.missing.key', 'Fallback text'); // Returns 'Fallback text'
+```
+
+### Translation with Interpolation
+
+```typescript
+import { ti } from 'koto-react';
+
+// If translation is: "Hello, {{name}}! You have {{count}} items."
+const message = ti('greeting.message', { 
+  name: 'John', 
+  count: 5 
+});
+// Returns: "Hello, John! You have 5 items."
+```
+
+### Pluralization
+
+```typescript
+import { tp } from 'koto-react';
+
+// Translations:
+// "items.zero": "No items"
+// "items.one": "One item"  
+// "items.other": "{{count}} items"
+
+tp('items', 0);  // "No items"
+tp('items', 1);  // "One item"
+tp('items', 5);  // "5 items"
+```
+
+## Features
+
+- 🚀 **Automatic Caching**: Translations are cached in IndexedDB for offline access and faster loads
+- 🔄 **Background Updates**: Cached translations are served immediately while fresh data is fetched in the background
+- 📦 **Nested Keys**: Support for nested translation keys using dot notation
+- 🎯 **TypeScript Support**: Full TypeScript support with type definitions
+- 💾 **Offline Support**: Works offline using cached translations
+- 🔧 **Flexible API**: Use with React hooks or standalone functions
+
+## API Reference
+
+### HermesProvider
+
+The main provider component that manages translations.
+
+**Props:**
+- `apiKey` (string, required): Your API key for fetching translations
+- `defaultLocale` (string, required): The default locale to use
+- `apiUrl` (string, optional): Custom API endpoint URL
+- `children` (ReactNode, required): Your app components
+
+### useTranslation()
+
+Hook that returns translation utilities.
+
+**Returns:**
+- `t(key: string, fallback?: string): string` - Translation function
+- `locale: string` - Current locale
+- `loading: boolean` - Loading state
+
+### t(key: string, fallback?: string): string
+
+Standalone translation function.
+
+**Parameters:**
+- `key`: The translation key (supports dot notation)
+- `fallback`: Optional fallback value if translation not found
+
+**Returns:** The translated string or the key if not found
+
+### Storage
+
+Translations are automatically cached in IndexedDB with:
+- 1-hour cache duration (configurable)
+- Automatic cleanup of expired entries
+- Per-locale storage
+
+## License
+
+MIT

package/dist/Provider.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import { KotoConfig, KotoContextValue, LocaleInfo } from './types';
+export interface KotoProviderProps extends KotoConfig {
+    children: React.ReactNode;
+}
+export declare function KotoProvider({ children, apiKey, projectId, defaultLocale, apiUrl }: KotoProviderProps): React.JSX.Element;
+export declare function useKoto(): KotoContextValue;
+export declare function useTranslation(): {
+    t: (key: string, fallback?: string) => string;
+    locale: string;
+    loading: boolean;
+    setLocale: (locale: string) => void;
+    availableLocales: LocaleInfo[];
+    getAvailableLocales: () => LocaleInfo[];
+};
+//# sourceMappingURL=Provider.d.ts.map

package/dist/Provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Provider.d.ts","sourceRoot":"","sources":["../src/Provider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA+E,MAAM,OAAO,CAAC;AACpG,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAmB,UAAU,EAAE,MAAM,SAAS,CAAC;AAOpF,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACnD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAID,wBAAgB,YAAY,CAAC,EAC3B,QAAQ,EACR,MAAM,EACN,SAAS,EACT,aAAa,EACb,MAA+C,EAChD,EAAE,iBAAiB,qBAqHnB;AAGD,wBAAgB,OAAO,IAAI,gBAAgB,CAM1C;AAGD,wBAAgB,cAAc;;;;;;;EAG7B"}

package/dist/constants/locales.d.ts

@@ -0,0 +1,20 @@
+export declare const SUPPORTED_LOCALES: {
+    readonly EN: "en";
+    readonly ES: "es";
+    readonly FR: "fr";
+    readonly DE: "de";
+    readonly IT: "it";
+    readonly PT: "pt";
+    readonly RU: "ru";
+    readonly ZH: "zh";
+    readonly JA: "ja";
+    readonly KO: "ko";
+    readonly AR: "ar";
+    readonly HI: "hi";
+};
+export type SupportedLocale = typeof SUPPORTED_LOCALES[keyof typeof SUPPORTED_LOCALES];
+export declare const DEFAULT_LOCALE: SupportedLocale;
+export declare const LOCALE_NAMES: Record<SupportedLocale, string>;
+export declare function isValidLocale(locale: string): locale is SupportedLocale;
+export declare function getLocaleName(locale: SupportedLocale): string;
+//# sourceMappingURL=locales.d.ts.map

package/dist/constants/locales.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locales.d.ts","sourceRoot":"","sources":["../../src/constants/locales.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;CAapB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,OAAO,iBAAiB,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAEvF,eAAO,MAAM,cAAc,EAAE,eAAsC,CAAC;AAEpE,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAaxD,CAAC;AAEF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,IAAI,eAAe,CAEvE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAE7D"}

package/dist/hoc.d.ts

@@ -0,0 +1,33 @@
+import React, { ComponentType } from 'react';
+import { KotoContextValue } from './types';
+/**
+ * Higher-Order Component for class components
+ * Wraps a component and injects translation props
+ */
+export declare function withTranslation<P extends object>(Component: ComponentType<P & WithTranslationProps>): ComponentType<Omit<P, keyof WithTranslationProps>>;
+/**
+ * Props injected by withTranslation HOC
+ */
+export interface WithTranslationProps {
+    t: KotoContextValue['t'];
+    locale: KotoContextValue['locale'];
+    loading: KotoContextValue['loading'];
+    setLocale: KotoContextValue['setLocale'];
+    translations?: KotoContextValue['translations'];
+    error?: KotoContextValue['error'];
+}
+/**
+ * Render prop component for more flexible usage
+ */
+export interface TranslationProps {
+    children: (props: KotoContextValue) => React.ReactNode;
+}
+export declare function Translation({ children }: TranslationProps): React.JSX.Element;
+/**
+ * Consumer component for direct context access
+ * Useful for class components that need conditional rendering
+ */
+export declare class KotoConsumer extends React.Component<TranslationProps> {
+    render(): React.JSX.Element;
+}
+//# sourceMappingURL=hoc.d.ts.map

package/dist/hoc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hoc.d.ts","sourceRoot":"","sources":["../src/hoc.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAC9C,SAAS,EAAE,aAAa,CAAC,CAAC,GAAG,oBAAoB,CAAC,GACjD,aAAa,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,oBAAoB,CAAC,CAAC,CAoBpD;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACzB,MAAM,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACnC,OAAO,EAAE,gBAAgB,CAAC,SAAS,CAAC,CAAC;IACrC,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,YAAY,CAAC,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC;IAChD,KAAK,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC;CACxD;AAED,wBAAgB,WAAW,CAAC,EAAE,QAAQ,EAAE,EAAE,gBAAgB,qBAGzD;AAED;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK,CAAC,SAAS,CAAC,gBAAgB,CAAC;IACjE,MAAM;CAGP"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { KotoProvider, useKoto, useTranslation } from './Provider';
+export type { KotoProviderProps } from './Provider';
+export { withTranslation, Translation, KotoConsumer } from './hoc';
+export type { WithTranslationProps, TranslationProps } from './hoc';
+export { t, ti, tp, initTranslations, setTranslations, getLocale } from './t';
+export { storage } from './storage';
+export type { TranslationData, KotoConfig, KotoContextValue, StoredTranslations, LocaleInfo, } from './types';
+export { AVAILABLE_LOCALES, getLocaleInfo, isLocaleSupported, getFallbackLocale, resolveLocale } from './locales';
+export { getNestedTranslation, flattenTranslations, unflattenTranslations } from './utils';
+export { KotoProvider as HermesProvider, useKoto as useHermes } from './Provider';
+export { KotoConsumer as HermesConsumer } from './hoc';
+import { t } from './t';
+export default t;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACnE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AACnE,YAAY,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAGpE,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAG9E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,YAAY,EACV,eAAe,EACf,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,GACX,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACd,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAG3F,OAAO,EAAE,YAAY,IAAI,cAAc,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,YAAY,IAAI,cAAc,EAAE,MAAM,OAAO,CAAC;AAGvD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,eAAe,CAAC,CAAC"}