@nlabs/metropolisjs 0.1.2 → 0.3.0

package/examples/i18n-import-examples.ts

@@ -0,0 +1,86 @@
+/**
+ * Copyright (c) 2025-Present, Nitrogen Labs, Inc.
+ * Copyrights licensed under the MIT License. See the accompanying LICENSE file for terms.
+ */
+
+// This file demonstrates different ways to import i18next functions
+// for consistency across MetropolisJS and GothamJS
+
+// Method 1: Direct import (original i18next way)
+import { t } from 'i18next';
+
+// Method 2: Aliased import for consistency (recommended)
+import { t as i18n } from 'i18next';
+
+// Method 3: Multiple imports with aliases
+import { t as translate } from 'i18next';
+
+// Example usage showing the difference:
+
+// Using the original 't' function
+const originalWay = () => {
+  const welcome = t('welcome');
+  const greeting = t('hello_user', {name: 'John'});
+  return {welcome, greeting};
+};
+
+// Using the aliased 'i18n' function (same as MetropolisJS)
+const consistentWay = () => {
+  const welcome = i18n('welcome');
+  const greeting = i18n('hello_user', {name: 'John'});
+  return {welcome, greeting};
+};
+
+// Using the 'translate' alias
+const alternativeWay = () => {
+  const welcome = translate('welcome');
+  const greeting = translate('hello_user', {name: 'John'});
+  return {welcome, greeting};
+};
+
+// Real-world example: GothamJS component
+const GothamJSComponent = () => {
+  // In GothamJS, you would use:
+  // import {t as i18n} from 'i18next';
+
+  // This gives you the same function name as MetropolisJS
+  const title = i18n('gotham_title');
+  const description = i18n('gotham_description');
+  const buttonText = i18n('gotham_button');
+
+  return {
+    title,
+    description,
+    buttonText
+  };
+};
+
+// MetropolisJS component (for comparison)
+const MetropolisJSComponent = () => {
+  // In MetropolisJS, you would use:
+  // import {i18n} from './utils/i18n';
+  // (which internally uses i18next)
+
+  const title = i18n('metropolis_title');
+  const description = i18n('metropolis_description');
+  const buttonText = i18n('metropolis_button');
+
+  return {
+    title,
+    description,
+    buttonText
+  };
+};
+
+// Benefits of using {t as i18n}:
+const benefits = {
+  consistency: 'Same function name across libraries',
+  familiarity: 'Developers know what i18n() does',
+  maintainability: 'Easier to switch between libraries',
+  clarity: 'Clear that it\'s for internationalization'
+};
+
+export {
+    alternativeWay, benefits, consistentWay, GothamJSComponent,
+    MetropolisJSComponent, originalWay
+};

package/examples/i18n-namespace-usage.ts

@@ -0,0 +1,118 @@
+/**
+ * Copyright (c) 2025-Present, Nitrogen Labs, Inc.
+ * Copyrights licensed under the MIT License. See the accompanying LICENSE file for terms.
+ */
+import { i18n, initI18n, updateI18nResources } from '../src/utils/i18n';
+
+const translations = {
+  'welcome:en': {
+    key: 'welcome',
+    locale: 'en',
+    value: 'Welcome {{name}}!',
+    namespace: 'common'
+  },
+  'save:en': {
+    key: 'save',
+    locale: 'en',
+    value: 'Save',
+    namespace: 'buttons'
+  },
+  'cancel:en': {
+    key: 'cancel',
+    locale: 'en',
+    value: 'Cancel',
+    namespace: 'buttons'
+  },
+  'login:en': {
+    key: 'login',
+    locale: 'en',
+    value: 'Login to your account',
+    namespace: 'auth'
+  },
+  'welcome:es': {
+    key: 'welcome',
+    locale: 'es',
+    value: '¡Bienvenido {{name}}!',
+    namespace: 'common'
+  },
+  'save:es': {
+    key: 'save',
+    locale: 'es',
+    value: 'Guardar',
+    namespace: 'buttons'
+  }
+};
+
+const initializeTranslations = () => {
+  initI18n(translations);
+  console.log('i18n initialized with namespaces');
+};
+
+const demonstrateNamespaceUsage = () => {
+  console.log('\n=== Namespace Usage Examples ===');
+
+  console.log('Default namespace (translations):');
+  console.log(i18n('welcome', {name: 'World'}));
+  console.log(i18n('welcome', {name: 'World'}, 'en'));
+
+  console.log('\nCommon namespace:');
+  console.log(i18n('welcome', {name: 'World'}, 'en', 'common'));
+  console.log(i18n('welcome', {name: 'Mundo'}, 'es', 'common'));
+
+  console.log('\nButtons namespace:');
+  console.log(i18n('save', {}, 'en', 'buttons'));
+  console.log(i18n('cancel', {}, 'en', 'buttons'));
+  console.log(i18n('save', {}, 'es', 'buttons'));
+
+  console.log('\nAuth namespace:');
+  console.log(i18n('login', {}, 'en', 'auth'));
+};
+
+const demonstrateDynamicUpdates = () => {
+  console.log('\n=== Dynamic Updates ===');
+
+  const newTranslations = {
+    'delete:en': {
+      key: 'delete',
+      locale: 'en',
+      value: 'Delete',
+      namespace: 'buttons'
+    },
+    'edit:en': {
+      key: 'edit',
+      locale: 'en',
+      value: 'Edit {{item}}',
+      namespace: 'actions'
+    }
+  };
+
+  updateI18nResources(newTranslations);
+
+  console.log('New button translation:');
+  console.log(i18n('delete', {}, 'en', 'buttons'));
+
+  console.log('New action translation:');
+  console.log(i18n('edit', {item: 'profile'}, 'en', 'actions'));
+};
+
+const demonstrateFallbacks = () => {
+  console.log('\n=== Fallback Behavior ===');
+
+  console.log('Missing key (returns key):');
+  console.log(i18n('missing-key', {}, 'en', 'common'));
+
+  console.log('Missing namespace (uses default):');
+  console.log(i18n('welcome', {name: 'World'}, 'en', 'missing-ns'));
+
+  console.log('Missing language (uses fallback):');
+  console.log(i18n('welcome', {name: 'World'}, 'fr', 'common'));
+};
+
+const runExamples = () => {
+  initializeTranslations();
+  demonstrateNamespaceUsage();
+  demonstrateDynamicUpdates();
+  demonstrateFallbacks();
+};
+
+export { demonstrateNamespaceUsage, initializeTranslations, runExamples };

package/examples/i18next-singleton-demo.ts

@@ -0,0 +1,187 @@
+/**
+ * Copyright (c) 2025-Present, Nitrogen Labs, Inc.
+ * Copyrights licensed under the MIT License. See the accompanying LICENSE file for terms.
+ */
+
+// This file demonstrates how i18next works as a singleton
+// and how GothamJS can share the same instance as MetropolisJS
+
+import { changeLanguage, init, t } from 'i18next';
+
+// Step 1: MetropolisJS initializes i18next (this happens in Metropolis component)
+const initializeMetropolisI18n = () => {
+  console.log('🔵 MetropolisJS: Initializing i18next...');
+
+  init({
+    resources: {
+      en: {
+        translations: {
+          'welcome': 'Welcome to MetropolisJS!',
+          'save': 'Save',
+          'cancel': 'Cancel',
+          'shared_text': 'This text is shared between libraries',
+          'hello_user': 'Hello {{name}}!'
+        }
+      },
+      es: {
+        translations: {
+          'welcome': '¡Bienvenido a MetropolisJS!',
+          'save': 'Guardar',
+          'cancel': 'Cancelar',
+          'shared_text': 'Este texto se comparte entre bibliotecas',
+          'hello_user': '¡Hola {{name}}!'
+        }
+      }
+    },
+    lng: 'en',
+    fallbackLng: 'en',
+    interpolation: {
+      escapeValue: false
+    }
+  });
+
+  console.log('🔵 MetropolisJS: i18next initialized successfully');
+};
+
+// Step 2: GothamJS can use the same i18next instance
+const gothamJSComponent = () => {
+  console.log('🟢 GothamJS: Using the same i18next instance');
+
+  // GothamJS can import {t as i18n} from 'i18next' for consistency
+  // This gives the same function name as MetropolisJS uses
+  // import {t as i18n} from 'i18next';
+
+  const gothamTitle = t('gotham_title', 'GothamJS Component'); // with fallback
+  const sharedText = t('shared_text'); // uses the same translation
+  const helloUser = t('hello_user', {name: 'Gotham User'}); // with interpolation
+
+  console.log('🟢 GothamJS translations:', {
+    gothamTitle,
+    sharedText,
+    helloUser
+  });
+
+  return {
+    title: gothamTitle,
+    description: sharedText,
+    greeting: helloUser
+  };
+};
+
+// Step 3: Demonstrate language switching affects both libraries
+const demonstrateLanguageSwitching = async () => {
+  console.log('\n🌍 Demonstrating language switching...');
+
+  // Both MetropolisJS and GothamJS will see this change
+  await changeLanguage('es');
+
+  console.log('🔄 Language changed to Spanish');
+
+  // MetropolisJS component
+  const metropolisText = t('welcome');
+  console.log('🔵 MetropolisJS (Spanish):', metropolisText);
+
+  // GothamJS component - automatically uses Spanish now
+  const gothamText = t('shared_text');
+  console.log('🟢 GothamJS (Spanish):', gothamText);
+
+  // Switch back to English
+  await changeLanguage('en');
+  console.log('🔄 Language changed back to English');
+
+  console.log('🔵 MetropolisJS (English):', t('welcome'));
+  console.log('🟢 GothamJS (English):', t('shared_text'));
+};
+
+// Step 4: Show how namespaces work across libraries
+const demonstrateNamespaces = () => {
+  console.log('\n📚 Demonstrating namespaces...');
+
+  // MetropolisJS might use 'metropolis' namespace
+  const metropolisText = t('dashboard_title', {ns: 'metropolis'});
+
+  // GothamJS might use 'gotham' namespace
+  const gothamText = t('widget_title', {ns: 'gotham'});
+
+  // Both can use 'common' namespace for shared translations
+  const commonText = t('shared_button', {ns: 'common'});
+
+  console.log('🔵 MetropolisJS namespace:', metropolisText);
+  console.log('🟢 GothamJS namespace:', gothamText);
+  console.log('🟡 Common namespace:', commonText);
+};
+
+// Step 5: Real-world usage example
+const realWorldExample = () => {
+  console.log('\n🏗️ Real-world usage example:');
+
+  // In a real React app:
+
+  // MetropolisJS component
+  const MetropolisComponent = () => {
+    // This would be in a MetropolisJS component
+    const title = t('dashboard_title');
+    const saveButton = t('save');
+
+    console.log('🔵 MetropolisJS component:', {title, saveButton});
+
+    return {title, saveButton};
+  };
+
+  // GothamJS component
+  const GothamComponent = () => {
+    // This would be in a GothamJS component
+    // import {t} from 'i18next'; // Same i18next instance!
+
+    const widgetTitle = t('widget_title');
+    const sharedButton = t('shared_button');
+
+    console.log('🟢 GothamJS component:', {widgetTitle, sharedButton});
+
+    return {widgetTitle, sharedButton};
+  };
+
+  const metropolis = MetropolisComponent();
+  const gotham = GothamComponent();
+
+  console.log('✅ Both components use the same i18next instance!');
+  console.log('✅ Language changes affect both components!');
+  console.log('✅ Namespaces keep translations organized!');
+
+  return {metropolis, gotham};
+};
+
+// Run the demonstration
+const runDemo = () => {
+  console.log('🚀 i18next Singleton Demonstration');
+  console.log('=====================================\n');
+
+  // Initialize i18next (MetropolisJS does this)
+  initializeMetropolisI18n();
+
+  // GothamJS uses the same instance
+  const gothamResult = gothamJSComponent();
+
+  // Demonstrate language switching
+  demonstrateLanguageSwitching();
+
+  // Demonstrate namespaces
+  demonstrateNamespaces();
+
+  // Real-world example
+  const realWorld = realWorldExample();
+
+  console.log('\n✅ Demonstration complete!');
+  console.log('✅ GothamJS can fully share i18next with MetropolisJS');
+  console.log('✅ Both libraries benefit from the same translation system');
+
+  return {
+    gothamResult,
+    realWorld
+  };
+};
+
+export {
+    demonstrateLanguageSwitching,
+    demonstrateNamespaces, gothamJSComponent, initializeMetropolisI18n, realWorldExample, runDemo
+};