# Runtime Localization Middleware for UI Systems (`aurumworks/runtime-localization-middleware-for-ui-systems`) Actor

A "localization middleware" that takes your source language interface strings and converts them into production-ready localized files for any target language.

- **URL**: https://apify.com/aurumworks/runtime-localization-middleware-for-ui-systems.md
- **Developed by:** [Aryan Saxena](https://apify.com/aurumworks) (community)
- **Categories:** Developer tools, AI, Automation
- **Features:** Limited permissions
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.01 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Runtime Localization Middleware for UI Systems

**Production-safe localization middleware for UI systems. Prevents broken interfaces, preserves UX integrity, and integrates into CI/CD pipelines.**

***

### What This Actor Does

Runtime Localization Middleware for UI Systems is **not** a generic translation tool. It's a **localization middleware** specifically engineered for **UI string safety**.

A mistranslated UI error can break onboarding, compliance, or conversions — this Actor prevents that.

#### Core Capabilities

| Feature | What It Means |
|---------|---------------|
| **UX Integrity Lock** | Error messages remain errors. Warnings stay warnings. Confirmation prompts stay cautious. No tone softening that breaks UX. |
| **Placeholder Preservation** | Variables like `{{name}}`, `{count}`, `%s` are **never** mistranslated or corrupted |
| **Structured Localization** | Handles JSON/YAML i18n bundles, not just raw text |
| **Tone Enforcement** | Apply `friendly`, `formal`, or `neutral` tones consistently across all languages |
| **Batch Processing** | Translate entire locale files into 10+ languages in a single run |

***

### Why This Exists

This Actor is intentionally **not designed** for documentation, blogs, or long-form text.

It solves a specific, high-stakes problem:

> **UI text is code.** A broken translation = a broken app.

Generic translators don't understand:

- That `{{username}}` must stay exactly as `{{username}}`
- That "Cancel" in a destructive action context must remain cautious
- That error messages need severity preservation

This Actor does.

***

### Built for Automation

Designed to run inside **CI/CD pipelines**, **MCP servers**, and **agent workflows**.

#### Integration Examples

```bash
## CI/CD Pipeline (GitHub Actions)
- name: Localize UI strings
  run: |
    apify call your-username/runtime-ui-text-translator \
      -i '{"uiStrings": ${{ steps.extract.outputs.strings }}, "targetLanguages": ["fr","de","ja"]}'
```

```javascript
// MCP Server Integration
const localizedStrings = await apifyClient.call('runtime-ui-text-translator', {
    uiStrings: appStrings,
    targetLanguages: ['es', 'pt', 'zh'],
    tone: 'professional'
});
```

***

### Input Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `uiStrings` | Object | Yes | Key-value pairs of UI strings to localize |
| `targetLanguages` | Array | Yes | ISO 639-1 codes (e.g., `["fr", "de", "ja"]`) |
| `lingoApiKey` | String | Yes | Your Lingo.dev API key (stored securely) |
| `sourceLanguage` | String | No | Source language code (default: `en`) |
| `tone` | String | No | `friendly` | `professional` | `neutral` | `formal` | `casual` |
| `placeholders` | Array | No | Patterns to preserve (e.g., `["{{name}}", "{count}"]`) |

#### Example Input

```json
{
  "uiStrings": {
    "auth.login.title": "Welcome back",
    "auth.login.button": "Sign in",
    "auth.login.error": "Invalid email or password",
    "profile.greeting": "Hello, {{username}}",
    "checkout.confirm": "Are you sure you want to proceed?"
  },
  "sourceLanguage": "en",
  "targetLanguages": ["fr", "de", "es"],
  "tone": "professional",
  "placeholders": ["{{username}}"],
  "lingoApiKey": "YOUR_LINGO_API_KEY"
}
```

***

### Output

Localized strings are returned in the **same structure** as input, grouped by language:

```json
{
  "fr": {
    "auth.login.title": "Bon retour",
    "auth.login.button": "Se connecter",
    "auth.login.error": "Adresse e-mail ou mot de passe incorrect",
    "profile.greeting": "Bonjour, {{username}}",
    "checkout.confirm": "Êtes-vous sûr de vouloir continuer ?"
  },
  "de": {
    "auth.login.title": "Willkommen zurück",
    "auth.login.button": "Anmelden",
    "auth.login.error": "Ungültige E-Mail-Adresse oder Passwort",
    "profile.greeting": "Hallo, {{username}}",
    "checkout.confirm": "Sind Sie sicher, dass Sie fortfahren möchten?"
  }
}
```

#### Output Locations

- **Key-Value Store**: `OUTPUT` record contains the full localized JSON
- **Dataset**: Translation status summary for each language

***

### Architecture

```
+-------------------------------------------------------------+
|                    YOUR CI/CD / MCP / AGENT                 |
+-------------------------------------------------------------+
                              |
                              v
+-------------------------------------------------------------+
|           Runtime Localization Middleware for UI Systems    |
|  +--------------+  +--------------+  +-------------------+  |
|  |    Input     |--|   Lingo.dev  |--|  UX Integrity     |  |
|  |   Validator  |  |    Engine    |  |  Lock (Tone +     |  |
|  |              |  |              |  |  Severity)        |  |
|  +--------------+  +--------------+  +-------------------+  |
+-------------------------------------------------------------+
                              |
                              v
+-------------------------------------------------------------+
|              PRODUCTION-READY LOCALE FILES                  |
|         (fr.json, de.json, ja.json, es.json, ...)           |
+-------------------------------------------------------------+
```

***

### FAQ

#### Is this for translating documentation or READMEs?

**No.** This Actor is strictly for **UI strings** — short, context-heavy labels, buttons, error messages, and prompts. For long-form content, use a different tool.

#### How is this different from a generic translator?

Generic translators treat text as text. This Actor treats **UI text as code** — preserving placeholders, maintaining severity context, and enforcing tone consistency.

#### Can I use this in my CI/CD pipeline?

**Yes.** This is the primary use case. Run it on every build to generate fresh locale files automatically.

#### Is my API key safe?

Yes. The `lingoApiKey` field is marked as `isSecret` and is never exposed in logs or dataset output.

#### What happens if translation fails for a language?

The Actor logs the error and continues with other languages. The dataset output includes status for each language so you can handle failures gracefully.

***

### Resources

- [Lingo.dev Documentation](https://lingo.dev)
- [Apify Platform](https://apify.com)
- [i18next](https://www.i18next.com/) — Compatible i18n library
- [react-intl](https://formatjs.io/docs/react-intl/) — Compatible i18n library

***

### Support

For Actor issues, use the **Issues** tab on Apify.
For translation quality or Lingo.dev questions, refer to [Lingo.dev Documentation](https://lingo.dev).

# Actor input Schema

## `lingoApiKey` (type: `string`):

Your Lingo.dev API key. Required for authentication.

## `uiStrings` (type: `object`):

Key-value pairs of UI strings to be localized. Supports nested objects.

## `sourceLanguage` (type: `string`):

The language code of the source strings (e.g., 'en').

## `targetLanguages` (type: `array`):

List of language codes to translate into (e.g., 'fr', 'de').

## `tone` (type: `string`):

Desired tone of the translation.

## `placeholders` (type: `array`):

List of placeholder patterns to preserve (e.g., '{{username}}').

## Actor input object example

```json
{
  "uiStrings": {
    "login.title": "Welcome back",
    "login.button": "Sign in"
  },
  "sourceLanguage": "en",
  "targetLanguages": [
    "fr",
    "de"
  ],
  "tone": "neutral",
  "placeholders": [
    "{{username}}",
    "{count}"
  ]
}
```

# Actor output Schema

## `localizedStrings` (type: `string`):

No description

## `translationStatus` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "uiStrings": {
        "login.title": "Welcome back",
        "login.button": "Sign in"
    },
    "targetLanguages": [
        "fr",
        "de"
    ],
    "placeholders": [
        "{{username}}",
        "{count}"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("aurumworks/runtime-localization-middleware-for-ui-systems").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "uiStrings": {
        "login.title": "Welcome back",
        "login.button": "Sign in",
    },
    "targetLanguages": [
        "fr",
        "de",
    ],
    "placeholders": [
        "{{username}}",
        "{count}",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("aurumworks/runtime-localization-middleware-for-ui-systems").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "uiStrings": {
    "login.title": "Welcome back",
    "login.button": "Sign in"
  },
  "targetLanguages": [
    "fr",
    "de"
  ],
  "placeholders": [
    "{{username}}",
    "{count}"
  ]
}' |
apify call aurumworks/runtime-localization-middleware-for-ui-systems --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,aurumworks/runtime-localization-middleware-for-ui-systems"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/RyzqJFgd8GV0HwFah/builds/B6vSgt0SwqVrm0tUe/openapi.json
