@vtubers.tv/i18n

Official Node.js client library for the VTubers.TV Translation Service. This package provides a robust and type-safe way to handle internationalization in your Node.js applications.

Features

• 🔄 Automatic translation caching
• 🎯 Type-safe translation keys and parameters
• 🌐 Support for nested translation keys
• 🔍 Parameter interpolation
• ⚡ Async and sync translation methods
• 🛡️ Comprehensive error handling
• 📦 Zero dependencies (except axios)

Installation

Since this is an internal package, install it directly from the GitHub repository:

npm install git://github.com/vtuberstv/node-i18n.git
# or
yarn add git://github.com/vtuberstv/node-i18n.git

Quick Start

import { Translate } from '@vtubers.tv/i18n';

// Create a translator instance
const translator = new Translate('en_US', {
  serviceName: 'frontend', // Required: name of the service to fetch translations from
});

// Basic usage
const greeting = await translator.t('hello', { user: 'World' }); // Returns: "Hello, World"

// Nested translation keys
const loginButton = await translator.t('auth.login.button'); // Returns: "Log In"

// Multiple parameters
const welcome = await translator.t('welcome', { 
  site: 'VTubers.TV', 
  user: 'John' 
}); // Returns: "Welcome to VTubers.TV, John!"

Advanced Usage

Translation Client

The TranslationClient class provides direct access to the translation service API:

import { TranslationClient } from '@vtubers.tv/i18n';

// Create a client instance
const client = new TranslationClient({
  baseURL: 'https://i18n.vtubers.tv', // Optional, defaults to https://i18n.vtubers.tv
  timeout: 10000, // Optional, defaults to 10000ms
});

// Check service health
const isHealthy = await client.healthCheck();

// Get all available services
const services = await client.getServices();

// Get detailed information about a service
const serviceInfo = await client.getService('frontend');

// Get all translations for a service
const translations = await client.getServiceTranslations('frontend');

// Get a specific translation
const translation = await client.getTranslation('frontend', 'en_US');

// Manually refresh translations (might require authentication)
await client.refreshTranslations();

Synchronous Translation

For cases where translations are already loaded, you can use the synchronous method:

const translator = new Translate('en_US', { serviceName: 'frontend' });
await translator.initialize(); // Load translations first

// Use synchronous translation
const greeting = translator.tSync('hello', { user: 'World' });

Error Handling

The package provides comprehensive error handling:

import { Translate, TranslationError } from '@vtubers.tv/i18n';

const translator = new Translate('en_US', { serviceName: 'frontend' });

try {
  // This will throw if the translation key doesn't exist
  const missing = await translator.t('missing.key');
} catch (error) {
  if (error instanceof TranslationError) {
    console.error(`[VTubers.TV i18n] Translation error: ${error.message}`);
  } else {
    console.error(`[VTubers.TV i18n] Unexpected error: ${error}`);
  }
}

API Reference

Translate Class

The main class for handling translations with caching.

Constructor Options

interface TranslateOptions {
  serviceName?: string;  // Required: name of the service to fetch translations from
  baseURL?: string;      // Optional: custom base URL
  timeout?: number;      // Optional: custom timeout in ms
}

Methods

• t(key: string, params?: TranslationParams): Promise<string>

  • Asynchronously translates a key with optional parameter interpolation
  • Returns: The translated string with interpolated parameters
  • Throws: TranslationError if the key is not found

• tSync(key: string, params?: TranslationParams): string

  • Synchronously translates a key with optional parameter interpolation
  • Returns: The translated string with interpolated parameters
  • Throws: TranslationError if translations are not initialized or key is not found

TranslationClient Class

The client class for interacting with the translation service API.

Methods

• healthCheck(): Promise<boolean>

  • Checks if the translation service is healthy
  • Returns: true if the service is up, false otherwise

• getServices(): Promise<string[]>

  • Returns: List of all available translation services

• getService(service: string): Promise<Service>

  • Returns: Detailed information about a specific service
  • Throws: TranslationError if the service is not found

• getServiceTranslations(service: string): Promise<Record<string, Translation>>

  • Returns: All translations for a specific service
  • Throws: TranslationError if the service is not found

• getTranslation(service: string, locale: string): Promise<Translation>

  • Returns: A specific translation for a service and locale
  • Throws: TranslationError if the translation is not found

• refreshTranslations(): Promise<void>

  • Manually triggers a refresh of all translation data
  • Note: This endpoint might require authentication

Types

The package exports the following TypeScript types:

• TranslationParams: Record of string/number parameters for interpolation
• Translation: Complete translation set with metadata
• TranslationMetadata: Metadata about a translation
• Service: Information about a translation service
• Contributor: Information about translation contributors
• TranslationError: Custom error class for translation-related errors
• ClientOptions: Configuration options for the translation client

For detailed type definitions, see types.ts.

License

This project is licensed under the GPL-3.0 license.