feat: manually mirror opencoze's code from bytedance

Change-Id: I09a73aadda978ad9511264a756b2ce51f5761adf

frontend/packages/arch/i18n/README.md

@@ -0,0 +1,284 @@
+# @coze-arch/i18n
+
+A comprehensive internationalization (i18n) solution for the Coze platform, providing unified text localization and language management across all applications in the monorepo.
+
+## Features
+
+- **🌍 Multi-language Support**: Built-in support for English and Chinese (Simplified) with easy extensibility
+- **🎯 Type-safe Translations**: Full TypeScript support with auto-generated types for translation keys
+- **⚡ Multiple Integration Modes**: Support for both Eden.js projects and standalone applications
+- **🔌 Plugin Architecture**: Extensible plugin system with language detection and ICU formatting
+- **📱 React Integration**: Built-in React provider and context for seamless component integration
+- **🛡️ Fallback Handling**: Robust fallback mechanisms for missing translations
+- **🎨 Design System Integration**: Seamless integration with Coze Design components
+
+## Get Started
+
+### Installation
+
+Add the package to your project:
+
+```json
+{
+  "dependencies": {
+    "@coze-arch/i18n": "workspace:*"
+  }
+}
+```
+
+Then run:
+
+```bash
+rush update
+```
+
+### Basic Usage
+
+#### For Eden.js Projects
+
+Configure in your `edenx.config.ts`:
+
+```typescript
+import { locale } from '@coze-arch/i18n/locales';
+
+export default {
+  intl: {
+    mode: 'offline',
+    clientOptions: {
+      namespace: 'i18n',
+    },
+    intlOptions: {
+      fallbackLng: 'en',
+      ns: 'i18n',
+      lng: 'en',
+      resources: locale,
+    },
+  },
+};
+```
+
+Use in your components:
+
+```typescript
+import { I18n } from '@coze-arch/i18n';
+
+function MyComponent() {
+  const title = I18n.t('common.title');
+  const greeting = I18n.t('common.greeting', { name: 'User' });
+
+  return <h1>{title}</h1>;
+}
+```
+
+#### For Standalone Applications
+
+Initialize before rendering:
+
+```typescript
+import { initI18nInstance, I18n } from '@coze-arch/i18n/raw';
+import { createRoot } from 'react-dom/client';
+
+initI18nInstance({
+  lng: 'en',
+  ns: 'i18n'
+}).then(() => {
+  const root = createRoot(document.getElementById('root'));
+  root.render(<App />);
+});
+```
+
+Use translations:
+
+```typescript
+import { I18n } from '@coze-arch/i18n/raw';
+
+function App() {
+  const message = I18n.t('welcome.message');
+  return <div>{message}</div>;
+}
+```
+
+#### React Provider Integration
+
+```typescript
+import { I18nProvider } from '@coze-arch/i18n/i18n-provider';
+import { I18n } from '@coze-arch/i18n';
+
+function App() {
+  return (
+    <I18nProvider i18n={I18n}>
+      <YourComponents />
+    </I18nProvider>
+  );
+}
+```
+
+## API Reference
+
+### Core I18n Instance
+
+#### `I18n.t(key, options?, fallback?)`
+
+Translate a text key with optional interpolation and fallback.
+
+```typescript
+// Basic translation
+I18n.t('common.save')
+
+// With interpolation
+I18n.t('user.greeting', { name: 'John' })
+
+// With fallback
+I18n.t('missing.key', {}, 'Default text')
+```
+
+#### `I18n.setLang(language, callback?)`
+
+Change the current language.
+
+```typescript
+I18n.setLang('zh-CN', () => {
+  console.log('Language changed');
+});
+```
+
+#### `I18n.setLangWithPromise(language)`
+
+Change language with Promise-based API.
+
+```typescript
+await I18n.setLangWithPromise('en');
+```
+
+#### `I18n.language`
+
+Get the current language.
+
+```typescript
+const currentLang = I18n.language; // 'en' | 'zh-CN'
+```
+
+#### `I18n.getLanguages()`
+
+Get available languages.
+
+```typescript
+const languages = I18n.getLanguages(); // ['zh-CN', 'zh', 'en-US']
+```
+
+#### `I18n.dir()`
+
+Get text direction for current language.
+
+```typescript
+const direction = I18n.dir(); // 'ltr' | 'rtl'
+```
+
+### Initialization Functions
+
+#### `initI18nInstance(config?)`
+
+Initialize i18n for standalone applications.
+
+```typescript
+interface I18nConfig {
+  lng: 'en' | 'zh-CN';
+  ns?: string;
+  // Additional i18next options
+}
+
+await initI18nInstance({
+  lng: 'en',
+  ns: 'i18n'
+});
+```
+
+### React Components
+
+#### `I18nProvider`
+
+React context provider for i18n integration.
+
+```typescript
+interface I18nProviderProps {
+  children?: ReactNode;
+  i18n: Intl;
+}
+```
+
+### Type Utilities
+
+#### `I18nKeysNoOptionsType`
+
+Type for translation keys that don't require interpolation options.
+
+#### `I18nKeysHasOptionsType`
+
+Type for translation keys that require interpolation options.
+
+## Development
+
+### Updating Translations
+
+Pull the latest translations from the remote source:
+
+```bash
+rush pull-i18n
+```
+
+This will update the locale files in `src/resource/locales/`.
+
+### Adding New Locale Keys
+
+1. Add new keys to the remote translation system
+2. Run `rush pull-i18n` to sync locally
+3. The TypeScript types will be automatically updated
+
+### Testing
+
+Run the test suite:
+
+```bash
+rushx test
+```
+
+Run tests with coverage:
+
+```bash
+rushx test:cov
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts              # Main export for Eden.js projects
+├── raw/                  # Standalone application exports
+├── i18n-provider/        # React context provider
+├── intl/                 # Core i18n implementation
+├── resource/             # Locale data and resources
+└── global.d.ts          # Global type definitions
+```
+
+## Dependencies
+
+### Core Dependencies
+
+- **i18next**: Core internationalization framework
+- **i18next-browser-languagedetector**: Automatic language detection in browsers
+- **i18next-icu**: ICU message formatting support
+- **@coze-studio/studio-i18n-resource-adapter**: Internal resource adapter for locale data
+- **@coze-arch/coze-design**: Design system integration
+
+### Peer Dependencies
+
+- **react**: React framework support
+- **react-dom**: React DOM rendering
+
+## License
+
+Internal package - ByteDance Ltd.
+
+---
+
+For questions or support, please contact the Coze Architecture team.