Polyglot JS

A JavaScript client for interacting with the Polyglot API. This library provides a simple and intuitive interface for managing translations, languages, and spaces in your Polyglot projects.

Installation

npm install polyglot-js

Usage

Initialize the client

import { PolyglotClient } from "polyglot-js";

const client = new PolyglotClient({
  organizationSlug: "your-organization",
  apiKey: "your-api-key",
});

Working with Languages

// Get all languages
const languages = await client.getLanguages();

// Create a new language
const newLanguage = await client.createLanguage({
  name: "Spanish",
  code: "es",
  isDefault: false,
  isAutoTranslatable: true,
});

// Update a language
await client.updateLanguage("language-id", {
  name: "Spanish (Updated)",
  isAutoTranslatable: false,
});

Working with Spaces

// Get all spaces
const spaces = await client.getSpaces();

// Create a new space
const newSpace = await client.createSpace({
  name: "Website",
  description: "Translations for our website",
});

Working with Translations

// Get all translations for a language and space
const translations = await client.getTranslations({
  languageId: "language-id",
  spaceId: "space-id",
});

// Get a specific translation
const translation = await client.getTranslation({
  languageId: "language-id",
  spaceId: "space-id",
  key: "welcome.message",
});

// Create or update a translation
await client.setTranslation({
  languageId: "language-id",
  spaceId: "space-id",
  key: "welcome.message",
  value: "Welcome to our application!",
});

// Update multiple translations at once
await client.updateTranslations({
  languageId: "language-id",
  spaceId: "space-id",
  translations: {
    "welcome.message": "Welcome to our application!",
    "goodbye.message": "Thank you for using our application!",
  },
});

Using the Translator

The PolyglotTranslator provides a convenient way to load and use translations in your application:

import { PolyglotClient, PolyglotTranslator } from "polyglot-js";

// Create a client
const client = new PolyglotClient({
  organizationSlug: "your-organization",
  apiKey: "your-api-key",
});

// Create a translator
const translator = new PolyglotTranslator({
  client: client,
  defaultLocale: "en",
  autoLoadSpaces: true, // Automatically load spaces when translating
});

// Load a space manually
await translator.loadSpace("common");

// Basic translation
translator.t("common.hello"); // "Hello"

// Translation with placeholder
translator.t("common.welcome", {
  replace: { name: "John" },
}); // "Welcome, John"

// Translation with pluralization
translator.t("common.items", { n: 0 }); // "No items"
translator.t("common.items", { n: 1 }); // "1 item"
translator.t("common.items", { n: 5 }); // "5 items"

// Change locale
await translator.setLocale("fr");

// Get current locale
const currentLocale = translator.getLocale(); // "fr"

Pluralization

The translator supports pluralization with the following format:

"No items|One item|{number} items"

Or the simpler format:

"One item|{number} items"

Placeholders

You can use placeholders in your translations:

"Welcome, {name}!"

And replace them when translating:

translator.t("common.welcome", {
  replace: { name: "John" },
}); // "Welcome, John!"

Error Handling

The client throws descriptive errors when API requests fail:

try {
  await client.getLanguages();
} catch (error) {
  console.error("API Error:", error.message);
  console.error("Status Code:", error.statusCode);
}

Advanced Configuration

const client = new PolyglotClient({
  baseUrl: "https://your-api-url.com",
  organizationSlug: "your-organization",
  apiKey: "your-api-key",
  timeout: 10000, // 10 seconds
  retries: 3, // Retry failed requests 3 times
});

Development

This package is built using Rolldown, a Rust-based JavaScript bundler that's compatible with Rollup's API but offers significantly faster build times.

Building the Package

To build the package, run:

npm run build

Running Tests

This package uses Vitest for testing. Vitest is a modern test runner that's fast and has a Jest-compatible API.

To run the tests:

# Run tests once
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

The test suite includes comprehensive tests for:

• The base client functionality
• Enhanced client with validation and caching
• Validation utilities
• Cache implementation

Current test coverage for source files is over 95%, ensuring high reliability of the codebase.

License

MIT