@zohodesk/client_build_tool 0.0.11-exp.26.0 → 0.0.11-exp.28.0

package/docs/I18N_NUMERIC_INDEXING_PLUGIN.md

@@ -1,225 +0,0 @@
-# I18n Numeric Indexing Plugin Documentation
-
-## Overview
-The I18nNumericIndexPlugin is a webpack plugin that implements lazy loading for i18n translations with numeric indexing to reduce bundle size. It separates translations into multiple chunks that load on-demand.
-
-## Features
-
-### 1. **Numeric Indexing**
-- Replaces string keys with numeric IDs (e.g., "support.label.home" → "1")
-- Reduces bundle size by ~40%
-- Maintains backward compatibility
-
-### 2. **Custom Group Support**
-- Define translation groups using banner markers in JSResources.properties
-- Each group generates a separate chunk
-- Groups load automatically when their associated code chunks load
-
-### 3. **Lazy Loading**
-- Initial load: Only numeric.i18n.js and dynamic.i18n.js
-- Setup translations: Load only when SetupHome chunk loads
-- Other groups: Load on-demand based on configuration
-
-## Configuration
-
-### In `cbt.config.js`:
-
-```javascript
-exports.config = {
-  i18nIndexing: {
-    enable: true,
-    jsResourcePath: './deskapp/properties/JSResources.properties',
-    propertiesFolderPath: './deskapp/properties',
-    numericMapPath: './deskapp/properties/i18n-numeric-map.json',
-    numericFilenameTemplate: 'i18n-chunk/[locale]/numeric.i18n.js',
-    dynamicFilenameTemplate: 'i18n-chunk/[locale]/dynamic.i18n.js',
-    jsonpFunc: 'window.loadI18nChunk',
-    htmlTemplateLabel: '{{--user-locale}}',
-    localeVarName: 'window.userLangCode',
-    customGroups: {
-      setup: {
-        bannerStart: '#SETUP_LAZY_KEYS STARTS',
-        bannerEnd: '#SETUP_LAZY_KEYS ENDS',
-        chunks: ['SetupHome'],  // Webpack chunks that trigger this group
-        filenameTemplate: 'i18n-chunk/[locale]/setup.i18n.js',
-        preload: false,
-        prefetch: true
-      }
-    }
-  }
-}
-```
-
-### In `JSResources.properties`:
-
-```properties
-# Regular translations
-support.label.home=Home
-support.label.tickets=Tickets
-
-#SETUP_LAZY_KEYS STARTS
-# These will be lazy loaded
-support.setup.label.phone=Phone
-support.setup.label.layouts_fields=Layouts and Fields
-#SETUP_LAZY_KEYS ENDS
-
-# More regular translations
-support.label.chat=Chat
-```
-
-### In `index.html`:
-
-```javascript
-window.loadI18nChunk = function(translations, groupName) {
-  // Merge translations
-  window.i18n = Object.assign(window.i18n, translations);
-  
-  // Track loaded groups
-  if (groupName) {
-    console.log('[I18n] Loaded group:', groupName);
-  }
-  
-  // Notify framework
-  window.dispatchEvent(new CustomEvent('i18nLoaded', { 
-    detail: { group: groupName } 
-  }));
-};
-```
-
-## How It Works
-
-### Build Time:
-1. Plugin reads JSResources.properties
-2. Parses banner markers to identify custom groups
-3. Generates numeric mapping for all keys
-4. Creates separate chunks:
-   - `numeric.i18n.js` - Main translations with numeric keys
-   - `dynamic.i18n.js` - Keys with placeholders (keep string keys)
-   - `setup.i18n.js` - Setup-specific translations (lazy loaded)
-
-### Runtime:
-1. Initial page load → Loads numeric.i18n.js + dynamic.i18n.js
-2. User clicks Setup → Webpack loads SetupHome.js
-3. Plugin runtime detects SetupHome needs 'setup' group
-4. Automatically loads setup.i18n.js
-5. Calls window.loadI18nChunk() with translations
-
-## Output Structure
-
-```
-agent/
-└── i18n-chunk/
-    ├── en_US/
-    │   ├── numeric.i18n.js    (396KB - main translations)
-    │   ├── dynamic.i18n.js    (201KB - dynamic keys)
-    │   └── setup.i18n.js      (217B - setup keys only!)
-    └── [other locales]/
-```
-
-## Generated Files
-
-### numeric.i18n.js:
-```javascript
-window.loadI18nChunk({
-  "1": "Home",
-  "2": "Tickets",
-  "3": "Chat"
-  // ... thousands more
-});
-```
-
-### setup.i18n.js:
-```javascript
-window.loadI18nChunk({
-  "4547": "Phone",
-  "4548": "Zia",
-  "4549": "Layouts and Fields"
-  // ... setup-specific keys
-}, "setup");
-```
-
-### i18n-numeric-map.json:
-```json
-{
-  "support.label.home": 1,
-  "support.label.tickets": 2,
-  "support.setup.label.phone": 4547
-}
-```
-
-## Using webpackI18nGroup Comments
-
-You can also mark chunks for i18n groups using comments:
-
-```javascript
-const SetupHome = lazy(() => 
-  import(
-    /* webpackChunkName: "SetupHome" */
-    /* webpackI18nGroup: "setup" */
-    './pages/SetupHome'
-  )
-);
-```
-
-## Performance Benefits
-
-1. **Initial Bundle**: ~40% smaller due to numeric indexing
-2. **Setup Keys**: Only 217 bytes, loaded on-demand
-3. **Network**: Fewer bytes transferred
-4. **Memory**: Reduced memory footprint
-
-## Adding New Groups
-
-To add a new lazy-loaded group (e.g., "reports"):
-
-1. Add banner markers in JSResources.properties:
-```properties
-#REPORTS_LAZY_KEYS STARTS
-support.reports.label.dashboard=Dashboard
-#REPORTS_LAZY_KEYS ENDS
-```
-
-2. Update cbt.config.js:
-```javascript
-customGroups: {
-  setup: { /* ... */ },
-  reports: {
-    bannerStart: '#REPORTS_LAZY_KEYS STARTS',
-    bannerEnd: '#REPORTS_LAZY_KEYS ENDS',
-    chunks: ['ReportsHome'],
-    filenameTemplate: 'i18n-chunk/[locale]/reports.i18n.js'
-  }
-}
-```
-
-## Troubleshooting
-
-### Keys not in setup chunk:
-- Check banner markers are correct in JSResources.properties
-- Verify key is between STARTS and ENDS markers
-
-### Setup chunk not loading:
-- Ensure SetupHome is in the chunks array
-- Check browser DevTools Network tab
-- Verify window.loadI18nChunk is defined
-
-### Numeric mapping issues:
-- Check i18n-numeric-map.json is generated
-- Verify no duplicate keys
-- Ensure jsResourcePath is correct
-
-## Migration Guide
-
-1. Enable i18nIndexing in cbt.config.js
-2. Add banner markers to JSResources.properties
-3. Update index.html with loadI18nChunk function
-4. Build and test
-5. Monitor Network tab to verify lazy loading
-
-## Best Practices
-
-1. **Group Related Keys**: Keep setup keys together
-2. **Use Root Chunks**: Configure the main entry chunk for each section
-3. **Monitor Bundle Size**: Check generated file sizes
-4. **Test Loading**: Verify chunks load when expected
-5. **Keep Groups Small**: Aim for <1KB per lazy group

package/docs/I18N_SINGLE_FILE_MODE.md

@@ -1,126 +0,0 @@
-# I18n Single-File Mode Configuration
-
-## Overview
-Single-file mode combines numeric and dynamic i18n keys into a single JavaScript file per locale, creating a flat output structure ideal for CDN deployment.
-
-## Configuration
-
-```javascript
-i18nIndexing: {
-  enable: true,
-  outputFolder: 'i18n',
-  singleFile: true,
-  singleFileTemplate: '[locale].js',  // Key setting for single-file mode
-  includeContentHash: true,
-  generateManifest: true,
-  manifestPath: 'i18n/manifest.json',
-  // ... other options
-}
-```
-
-## Key Options
-
-### `singleFile: true`
-Enables single-file mode, combining all i18n keys into one file per locale.
-
-### `singleFileTemplate: '[locale].js'`
-Template for single-file naming. Default: `[locale].js`
-- `[locale]` is replaced with the actual locale code
-- Results in files like: `en_US.js`, `fr_FR.js`
-
-### `outputFolder: 'i18n'`
-Base directory for all i18n files. Files are placed directly here in single-file mode.
-
-### `includeContentHash: true`
-Adds content hash for cache busting:
-- Without hash: `i18n/en_US.js`
-- With hash: `i18n/en_US.abc123.js`
-
-### `manifestPath: 'i18n/manifest.json'`
-Custom location for the manifest file that maps original names to hashed versions.
-
-## Output Structure
-
-```
-build/
-├── i18n/
-│   ├── en_US.b9ef890a.js    # Combined file with content hash
-│   ├── fr_FR.3452451e.js    
-│   ├── de_DE.e8b84364.js
-│   └── manifest.json         # Mapping file
-```
-
-## Manifest Format
-
-The manifest provides a clean mapping without paths or type suffixes:
-
-```json
-{
-  "en_US.js": "en_US.b9ef890a.js",
-  "fr_FR.js": "fr_FR.3452451e.js",
-  "de_DE.js": "de_DE.e8b84364.js"
-}
-```
-
-## HTML Integration
-
-The HTML injector automatically adds the appropriate script tag based on the `htmlTemplateLabel`:
-
-```html
-<!-- With htmlTemplateLabel: '{{--user-locale}}' -->
-<script src="i18n/{{--user-locale}}.js"></script>
-```
-
-## Runtime Loading
-
-Files are loaded using the configured `jsonpFunc`:
-
-```javascript
-// File content example with jsonpFunc: 'var imAppI18n='
-var imAppI18n={"0":"Welcome","1":"Hello","dynamic.key":"Dynamic value"};
-```
-
-## Comparison: Single-File vs Multi-File Mode
-
-### Single-File Mode
-```javascript
-singleFile: true
-// Output: i18n/en_US.js (contains all keys)
-```
-
-### Multi-File Mode (Default)
-```javascript
-singleFile: false
-// Output: 
-//   i18n/en_US/numeric.i18n.js (numeric keys only)
-//   i18n/en_US/dynamic.i18n.js (dynamic keys only)
-```
-
-## Benefits of Single-File Mode
-
-1. **Fewer HTTP Requests**: One file per locale instead of multiple
-2. **Simpler Deployment**: Flat structure is easier to manage
-3. **CDN Friendly**: Clean paths work better with CDN caching
-4. **Clear Manifest**: Simple key-value mapping without complex paths
-
-## Example Configuration
-
-```javascript
-exports.config = {
-  i18nIndexing: {
-    enable: true,
-    outputFolder: 'i18n',
-    jsResourcePath: './resources/ApplicationResources.properties',
-    propertiesFolderPath: './resources',
-    numericMapPath: './numericMap.json',
-    singleFile: true,
-    singleFileTemplate: '[locale].js',
-    jsonpFunc: 'var imAppI18n=',
-    htmlTemplateLabel: '{{--user-locale}}',
-    localeVarName: 'window.userLangCode',
-    includeContentHash: true,
-    generateManifest: true,
-    manifestPath: 'i18n/imI18nManifest.json'
-  }
-};
-```