Localization

The Kinesis API includes a powerful localization system that makes it easy to translate your application into multiple languages. It supports features like variable interpolation, pluralization, and fallback locales.

Features

• Multiple Locale Support: Manage translations for any number of languages
• Fallback Chain: Automatically fallback to parent locales (e.g., "en" for "en-US")
• Variable Interpolation: Insert dynamic values into translations
• Pluralization Rules: Language-specific plural forms for accurate translations
• Hot Reloading: Automatically detect and reload modified translation files
• REST API: Manage translations through a RESTful API

Translation File Format

Translations are stored in JSON files, one per locale:

{
  "common": {
    "welcome": "Welcome to Kinesis API",
    "error": "An error occurred",
    "buttons": {
      "save": "Save",
      "cancel": "Cancel"
    }
  },
  "auth": {
    "login": "Log in",
    "logout": "Log out",
    "register": "Sign up"
  },
  "notifications": {
    "message_count": {
      "one": "You have {count} new message",
      "other": "You have {count} new messages"
    }
  }
}

These are accessed using dot notation (e.g., common.welcome, auth.login, notifications.message_count).

Managing Translations via Web UI

Kinesis API provides a user-friendly web interface for managing translations without needing to work directly with JSON files or API calls.

Accessing the Translation Manager

1. Log in to your Kinesis API instance
2. Navigate to /web/locales in your browser
3. You'll see a list of all available locales and their translations

Working with Locales

The top of the page displays available locales as buttons. Click any locale to view and manage its translations. The active locale is highlighted.

Creating Translations

1. Click the "Create a new translation" button at the top of the page
2. Enter the locale code (e.g., "en", "fr"), or use the pre-filled active locale
3. Enter the key (using dot notation, e.g., "common.buttons.save")
4. Enter the translation value
5. Click "Create" to add the translation

If you enter a locale that doesn't exist yet, it will be created automatically.

Filtering Translations

Use the filter box to quickly find translations by key or value. This is especially useful for locales with many translations.

Updating Translations

1. Find the translation you want to modify
2. Click the edit (pencil) icon
3. Enter the new translation value
4. Click "Submit" to save your changes

Deleting Translations

1. Find the translation you want to remove
2. Click the delete (trash) icon
3. Confirm the deletion when prompted

Permissions

Only users with ADMIN or ROOT roles can create, update, or delete translations. All users can view translations.

API Endpoints

Fetch All Locales

Get a list of all available locales and their translation counts.

GET /locale/fetch?uid=0
Authorization: Bearer <token>

Response:

{
  "status": 200,
  "message": "Locales successfully fetched!",
  "locales": [
    { "code": "en", "translation_count": 42 },
    { "code": "fr", "translation_count": 36 }
  ],
  "amount": 2
}

Fetch One Locale

Get all translations for a specific locale.

GET /locale/fetch/one?uid=0&locale=en
Authorization: Bearer <token>

Response:

{
  "status": 200,
  "message": "Locale successfully fetched!",
  "translations": {
    "common.welcome": "Welcome to Kinesis API",
    "common.error": "An error occurred",
    "common.buttons.save": "Save"
    // ... other translations
  }
}

Translate Text

Translate a specific key with optional variables and count for pluralization.

POST /locale/translate
Content-Type: application/json

{
  "locale": "en",
  "key": "notifications.message_count",
  "variables": {
    "user": "John"
  },
  "count": 5
}

Response:

{
  "status": 200,
  "message": "Translation successful!",
  "translation": "You have 5 new messages",
  "key": "notifications.message_count",
  "locale": "en"
}

Create Translation

Add a new translation key-value pair to a locale.

POST /locale/create
Content-Type: application/json
Authorization: Bearer <token>

{
  "uid": 0,
  "locale": "en",
  "key": "common.buttons.submit",
  "value": "Submit"
}

Response:

{
  "status": 200,
  "message": "Translation successfully added!",
  "locale": "en",
  "key": "common.buttons.submit"
}

Update Translation

Update an existing translation.

PATCH /locale/update
Content-Type: application/json
Authorization: Bearer <token>

{
  "uid": 0,
  "locale": "en",
  "key": "common.buttons.save",
  "value": "Save Changes"
}

Response:

{
  "status": 200,
  "message": "Translation successfully added!",
  "locale": "en",
  "key": "common.buttons.save"
}

Delete Translation

Delete a translation key from a locale.

DELETE /locale/delete?uid=0&locale=en&key=common.buttons.cancel
Authorization: Bearer <token>

Response:

{
  "status": 200,
  "message": "Translation successfully deleted!",
  "locale": "en",
  "key": "common.buttons.cancel"
}

Pluralization

The localization system supports proper pluralization rules for different languages. For example:

{
  "items_count": {
    "one": "You have {count} item",
    "other": "You have {count} items"
  }
}

For languages with more complex plural forms (like Slavic languages), additional forms are supported:

{
  "items_count": {
    "one": "У вас {count} элемент",
    "few": "У вас {count} элемента",
    "many": "У вас {count} элементов",
    "other": "У вас {count} элементов"
  }
}

The system automatically selects the correct plural form based on the count parameter and the language's pluralization rules.

Variable Interpolation

You can insert dynamic values into translations using curly braces:

{
  "welcome_user": "Welcome, {{name}}!"
}

Then provide the variables when translating:

{
  "locale": "en",
  "key": "welcome_user",
  "variables": {
    "name": "John"
  }
}

This will produce: "Welcome, John!"

Setup and Configuration

Translations are stored in JSON files in the /translations directory, with the filename matching the locale code (e.g., en.json, fr.json).

The localization system is initialized with all translations when Kinesis API is started.

Permissions

The following permissions are required for various localization operations:

• LOCALE_FETCH: Required to fetch locales and translations
• LOCALE_CREATE_UPDATE: Required to create or update translations
• LOCALE_DELETE: Required to delete translations

Best Practices

1. Structured Keys: Organize keys in a logical hierarchy (e.g., feature.component.text)
2. Complete Translations: Ensure all keys have translations in all supported locales
3. Reuse Common Phrases: Use the same key for identical text across different features
4. Avoid Variable Concatenation: Use variable interpolation instead of string concatenation
5. Test All Locales: Regularly test your application with all supported locales