Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@sucoza/i18n-devtools-plugin) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

i18n DevTools Plugin

A comprehensive internationalization debugging plugin for TanStack DevTools that provides real-time translation key tracking, missing key detection, language coverage analysis, formatting preview, bundle size optimization, and layout testing for multilingual React applications.

Features

🌐 Translation Key Management

Real-time translation key usage tracking and monitoring
Missing translation key detection with component source mapping
Translation key coverage analysis across languages and namespaces
Dynamic key generation and interpolation value tracking

🔍 Translation Coverage Analysis

Comprehensive language coverage reporting and statistics
Namespace-level translation completeness tracking
Translation quality assessment and consistency analysis
Dead key detection and cleanup recommendations

📝 Interactive Translation Editor

In-browser translation editing with real-time preview
Context-aware translation suggestions and validation
Pluralization and interpolation testing interface
Translation import/export functionality

🎨 Format & Layout Testing

Live formatting preview for dates, numbers, and currencies
RTL (Right-to-Left) layout testing and validation
Text expansion testing for different languages
UI component overflow and truncation detection

📦 Bundle Size Analysis

Translation bundle size analysis and optimization
Namespace-based bundle splitting recommendations
Unused translation detection and cleanup suggestions
Lazy loading impact analysis and recommendations

⚡ Performance Monitoring

Translation loading performance metrics and analysis
Cache hit rate monitoring and optimization
Translation lookup performance profiling
Memory usage analysis for large translation sets

🔧 Framework Integration

react-i18next integration with hook usage tracking
i18next configuration analysis and optimization
Custom i18n framework adapter support
Translation provider performance monitoring

Installation

npm install @sucoza/i18n-devtools-plugin

Usage

Basic Setup

import React from 'react';
import { I18nDevToolsPanel } from '@sucoza/i18n-devtools-plugin';

function App() {
  return (
    <div>
      {/* Your app content */}
      
      {/* i18n DevTools Panel */}
      <I18nDevToolsPanel />
    </div>
  );
}

With Event Client Integration

import React, { useEffect } from 'react';
import { 
  I18nDevToolsPanel,
  createI18nEventClient 
} from '@sucoza/i18n-devtools-plugin';

function App() {
  useEffect(() => {
    // Initialize the i18n event client
    const client = createI18nEventClient();
    
    // Optional: Listen for i18n events
    const unsubscribe = client.subscribe((event, type) => {
      if (type === 'i18n:missing-key') {
        console.log('Missing translation key detected:', event);
      }
      if (type === 'i18n:language-change') {
        console.log('Language changed:', event);
      }
      if (type === 'i18n:translation-updated') {
        console.log('Translation updated:', event);
      }
    });
    
    return unsubscribe;
  }, []);

  return (
    <div>
      <I18nDevToolsPanel />
    </div>
  );
}

React-i18next Integration

import React from 'react';
import { I18nDevToolsPanel, ReactI18nextAdapter } from '@sucoza/i18n-devtools-plugin';
import { useTranslation } from 'react-i18next';

function App() {
  const { i18n } = useTranslation();

  return (
    <div>
      <I18nDevToolsPanel 
        adapter={new ReactI18nextAdapter(i18n)}
      />
    </div>
  );
}

Using the Hook

import React from 'react';
import { useI18nDevTools } from '@sucoza/i18n-devtools-plugin';

function MyComponent() {
  const {
    currentLanguage,
    availableLanguages,
    missingKeys,
    translationKeys,
    performanceMetrics,
    changeLanguage,
    updateTranslation,
    addTranslationKey,
    analyzeBundle,
    testLayout
  } = useI18nDevTools();
  
  return (
    <div>
      <div>
        <h3>i18n Status</h3>
        <p>Current Language: {currentLanguage}</p>
        <p>Available Languages: {availableLanguages.length}</p>
        <p>Missing Keys: {missingKeys.length}</p>
        <p>Cache Hit Rate: {(performanceMetrics.cacheHitRate * 100).toFixed(1)}%</p>
      </div>
      
      <div>
        <h3>Language Switcher</h3>
        {availableLanguages.map(lang => (
          <button 
            key={lang.code}
            onClick={() => changeLanguage(lang.code)}
            className={lang.code === currentLanguage ? 'active' : ''}
          >
            {lang.name} ({lang.completeness}%)
          </button>
        ))}
      </div>
      
      {missingKeys.length > 0 && (
        <div>
          <h3>Missing Translation Keys</h3>
          {missingKeys.slice(0, 10).map(key => (
            <div key={key.key}>
              <p><strong>{key.namespace}:{key.key}</strong></p>
              <p>Used in: {key.usedAt.join(', ')}</p>
              <button onClick={() => updateTranslation(key.namespace, key.key, 'TODO: Add translation')}>
                Add Translation
              </button>
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

Configuration

Framework Adapter Setup

import { ReactI18nextAdapter } from '@sucoza/i18n-devtools-plugin';
import i18n from './i18n'; // Your i18next configuration

function MyComponent() {
  const adapter = new ReactI18nextAdapter(i18n, {
    trackUsage: true,
    detectMissingKeys: true,
    enablePerformanceMonitoring: true,
    enableBundleAnalysis: true,
  });

  return (
    <I18nDevToolsPanel adapter={adapter} />
  );
}

Analysis Options

import { useI18nDevTools } from '@sucoza/i18n-devtools-plugin';

function MyComponent() {
  const { updateAnalysisOptions } = useI18nDevTools();
  
  // Configure analysis behavior
  updateAnalysisOptions({
    trackKeyUsage: true,
    detectMissingKeys: true,
    analyzeBundleSize: true,
    enablePerformanceMetrics: true,
    enableLayoutTesting: true,
    maxKeysToTrack: 1000,
    bundleAnalysisInterval: 30000, // 30 seconds
  });
}

Testing Configuration

import { useI18nDevTools } from '@sucoza/i18n-devtools-plugin';

function MyComponent() {
  const { updateTestingOptions } = useI18nDevTools();
  
  // Configure layout testing
  updateTestingOptions({
    testLanguages: ['en', 'ar', 'de', 'ja'], // Languages to test
    enableRTLTesting: true,
    enableOverflowDetection: true,
    enableTruncationDetection: true,
    captureScreenshots: true,
    testViewports: ['mobile', 'tablet', 'desktop'],
  });
}

Components

I18nDevToolsPanel

The main panel component that provides the complete i18n debugging interface with multiple tabs.

Individual Components

You can also use individual components for specific functionality:

KeyExplorer - Translation key browser and search interface
LanguageSwitcher - Language selection and switching controls
MissingKeysPanel - Missing translation detection and management
TranslationEditor - In-browser translation editing interface
CoverageVisualization - Translation coverage charts and statistics
FormatPreview - Date, number, and currency formatting preview
BundleAnalyzer - Translation bundle size analysis
LayoutTester - Cross-language layout testing interface
PerformanceMetrics - i18n performance monitoring dashboard

API Reference

Types

interface TranslationKey {
  key: string;
  namespace: string;
  defaultValue?: string;
  interpolation?: Record<string, any>;
  count?: number;
  context?: string;
  usedAt: string[];
  lastUsed: number;
}

interface LanguageInfo {
  code: string;
  name: string;
  nativeName: string;
  isRTL: boolean;
  completeness: number;
  totalKeys: number;
  translatedKeys: number;
  missingKeys: string[];
  isDefault?: boolean;
  isActive?: boolean;
}

interface I18nState {
  currentLanguage: string;
  fallbackLanguage: string;
  availableLanguages: LanguageInfo[];
  namespaces: NamespaceInfo[];
  translations: Translation[];
  translationKeys: TranslationKey[];
  missingKeys: TranslationKey[];
  isLoading: boolean;
  lastUpdated: number;
}

interface I18nPerformanceMetrics {
  initTime: number;
  translationTime: number;
  bundleLoadTime: Record<string, number>;
  memoryUsage: number;
  cacheHitRate: number;
  missedTranslationsCount: number;
  averageKeyLookupTime: number;
}

Event Client

interface I18nEvents {
  'i18n:state': I18nState;
  'i18n:language-change': { from: string; to: string; timestamp: number };
  'i18n:missing-key': { key: TranslationKey; component: string };
  'i18n:translation-updated': { namespace: string; key: string; value: string };
  'i18n:key-usage': { key: TranslationKey; component: string };
  'i18n:bundle-loaded': { namespace: string; size: number; loadTime: number };
  'i18n:performance-metrics': I18nPerformanceMetrics;
  'i18n:layout-test': { language: string; results: LayoutTestResult[] };
}

Framework Adapters

interface I18nAdapter {
  getCurrentLanguage(): string;
  getAvailableLanguages(): LanguageInfo[];
  changeLanguage(language: string): Promise<void>;
  getTranslation(namespace: string, key: string): string | undefined;
  updateTranslation(namespace: string, key: string, value: string): void;
  getNamespaces(): NamespaceInfo[];
  trackKeyUsage(key: TranslationKey, component: string): void;
  getPerformanceMetrics(): I18nPerformanceMetrics;
}

class ReactI18nextAdapter implements I18nAdapter {
  constructor(i18nInstance: i18n, options?: AdapterOptions);
  // Implementation methods...
}

Examples

Check out the example/ directory for a complete demonstration of the plugin with various i18n configurations and testing scenarios.

To run the example:

cd example
npm install
npm run dev

The example includes:

react-i18next integration with multiple languages
Missing translation key scenarios
Layout testing with RTL languages
Translation bundle analysis examples
Performance monitoring demonstrations
Interactive translation editing examples

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT

Part of the @sucoza TanStack DevTools ecosystem.

Powered By

react-i18next - React internationalization framework
i18next - Internationalization framework
TanStack DevTools - Development tools framework
Zustand - State management
Intl - Native internationalization APIs