Project Resources API

API, CLI, and MCP

i18nexus gives developers three ways to connect their app and workflow to the same project data. The API, CLI, and MCP all work with i18nexus as the source of truth, but they are built for different jobs.

In practice, many teams use all three: MCP for AI-agent string changes, the dashboard for review, the CLI for local file sync, and the API for custom automation.

Authorization

The Project Resources API is a simple RESTful API for accessing your i18nexus project data. This API is located at the following base URL:

https://api.i18nexus.com/project_resources/

By default, all read-only endpoints can be accessed by including your project API key in the request. For example:

https://api.i18nexus.com/project_resources/translations.json?api_key=:your_api_key

For API endpoints that write project data, a Personal Access Token is required in the header of the request. Write requests must also include the project api_key query parameter:

Authorization: Bearer YOUR_TOKEN

Tokens are created per user with selected write permissions. The token must include the permission required by the endpoint, and the user must have a project role that can write to the project. Tokens are created in a user's account settings in the i18nexus Dashboard:

Get Project Resources

GET Project Metadata

Returns basic project settings that affect how API clients should create and update strings.

Use this endpoint to check the project library, base language, target languages, namespace mode, and whether description is used as AI translation context.

{
    "id": "c3ee93c5-66c8-487d-8cbb-0e6109550f35",
    "title": "My App",
    "library": "i18next",
    "language": "en",
    "languages": ["ar", "es"],
    "use_namespaces": true,
    "use_description_as_ai_context": true,
    "namespaces": ["common", "homepage"]
}

GET Translations: By language

Returns a JSON object of a project’s translations for all namespaces for a single language.

Optionally include param confirmed=true to retrieve only your confirmed translations

{
  "my-first-namespace": {
      "welcome": "Welcome to my app!",
      "goodbye": "Thanks for using my app!"
  },
  "my-second-namespace": {
      "greeting": "How are you?"
  }
}

GET Translations: By language and namespace

Returns a JSON object of a project’s translations for a specified language and namespace.

Optionally include param confirmed=true to retrieve only your confirmed translations

{
    "welcome": "Welcome to my app!",
    "goodbye": "Thanks for using my app!"
}

GET Translations: All

Returns a nested JSON object of all project translations for all languages and namespaces.

{
    "en": {
        "my-first-namespace": {
            "welcome": "Welcome to my app!",
            "goodbye": "Thanks for using my app!"
        },
        "my-second-namespace": {
            "greeting": "How are you?"
        }
    },
    "es-MX": {
        "my-first-namespace": {
            "welcome": "¡Bienvenido a mi aplicación!",
            "goodbye": "¡Gracias por usar mi aplicación!"
        },
        "my-second-namespace": {
            "greeting": "¿Cómo estás?"
        }
    }
}

GET Versions

Returns a collection of a project’s exported versions ordered from newest to oldest.

By default the latest 10 versions will be returned, but this can be adjusted using the optional limit query parameter.

{
    "collection": [
        {
            "created_at": 1631402817503,
            "description": "My version description",
            "download_url": "https://cdn.i18nexus.com/versions/1/translations.zip",
            "id": "c3ee93c5-66c8-487d-8cbb-0e6109550f35",
            "key_separation": true,
            "languages": ["en","es-MX"],
            "namespaces": ["my-first-namespace", "my-second-namespace"],
            "version_number": 1
        }
    ],
    "meta": {
        "limit": 10
    }
}

GET Namespaces

Returns a collection of a project’s namespaces.

{
    "collection": [
        {
            "id": "c3ee93c5-66c8-487d-8cbb-0e6109550f35",
            "title": "common",
            "created_at": 1631402817503
        },
        {
            "id": "77915b03-496d-4c48-83c0-cece670ff5b3",
            "title": "homepage",
            "created_at": 1633402920418
        }
    ]
}

GET Languages

Returns a collection of a project’s languages.

{
    "collection": [
        {
            "name": "English",
            "full_code": "en",
            "language_code": "en",
            "country_code": null,
            "google_translate_code": "en",
            "base_language": true
        },
        {
            "name": "Spanish",
            "full_code": "es",
            "language_code": "es",
            "country_code": null,
            "google_translate_code": "es",
            "base_language": false
        }
    ]
}

Write Project Resources (Advanced)

Almost all i18nexus users prefer using the following APIs through the i18nexus-cli, where each request is wrapped in a simple command. Direct access to the following APIs is meant for teams who want to integrate i18nexus into their own management systems and workflows.

Reminder: Write APIs are only authorized using Personal Access Tokens.

Create String

Creates a new string in your project’s base language, and automatically AI translates it for each of your project’s target languages. Translations are generated asynchronously, so target-language values may take a few seconds to appear.

Requires the Personal Access Token's create strings permission.

Parameters:

Example Request Body:

{
    "key": "welcome_msg",
    "value": "Welcome to my app!",
    "description": "Appears in the home page header.",
    "namespace": "homepage"
}

Create Plural Set

Creates a plural set in your project’s base language and automatically AI translates the correct plural categories for each target language. Use this for count-dependent text instead of creating separate singular and plural strings.

Requires the Personal Access Token's create strings permission. Translation generation is asynchronous.

Parameters:

Example Request Body:

{
    "key": "items_in_cart",
    "plural_values": {
        "one": "{{count}} item in your cart",
        "other": "{{count}} items in your cart"
    },
    "description": "Cart item count shown in checkout.",
    "namespace": "common"
}

Bulk Create Strings

Creates up to 500 base-language strings in one request and automatically AI translates them for each target language. Processing runs asynchronously.

Requires the Personal Access Token's create strings permission.

Parameters:

Example Request Body:

{
    "namespace": "common",
    "base_strings": [
        {
            "key": "welcome_msg",
            "value": "Welcome to my app!",
            "description": "Appears in the home page header."
        },
        {
            "key": "sign_in",
            "value": "Sign in"
        }
    ]
}

Example Response:

{
    "base_strings_invalid_values": []
}

Update String

Updates a string’s key, value, description, AI Notes, and/or namespace. Updating a value or AI translation context can trigger asynchronous retranslation.

Requires the Personal Access Token's update strings permission.

Parameters:

Example Request Body:

In this example we are changing the key and the value of the string with key notifications in namespace common.

{
    "id": {
        "key": "notifications",
        "namespace": "common"
    },
    "key": "notifications.alert",
    "value": "You have a new notification!",
    "reset_confirmed": true
}

Plural Set Example:

To update one base-language plural form, identify the root key and include plural_category. In this mode, only value may be changed.

For plural set responses, the root string's value is null; base-language plural values are returned in plural_forms.

{
    "id": {
        "key": "items_in_cart",
        "namespace": "common"
    },
    "plural_category": "one",
    "value": "{{count}} item in your cart",
    "reset_confirmed": true
}

Delete String

Deletes a string and its associated translations in your project. For plural sets, delete the root key. A successful delete returns 204 No Content.

Requires the Personal Access Token's delete strings permission.

Parameters:

Example Request Body:

In this example we are deleting the string with key notifications.alert from namespace common.

{
    "id": {
        "key": "notifications.alert",
        "namespace": "common"
    }
}

Bulk Delete Strings

Deletes up to 50 strings from one namespace. For plural sets, pass the root key. Deleted strings and their translations are permanently removed.

Requires the Personal Access Token's delete strings permission.

Parameters:

Example Request Body:

{
    "namespace": "common",
    "keys": ["welcome_msg", "notifications.alert"]
}

Example Response:

{
    "deleted_keys": ["welcome_msg", "notifications.alert"],
    "missing_keys": []
}

Import Strings from JSON

Imports a block of JSON key-value pairs into your project. This is the equivalent of using the Import tool in the Strings Management page. Imports run asynchronously and may take a few seconds or longer depending on their size.

Requires the Personal Access Token's import strings permission.

Parameters:

Example Request Body:

In this example we are importing strings into our project’s common namespace for English (en) and Spanish (es).

You do not have to include all of your projects’ languages in your request, only the ones you wish to update.

{
    "namespace": "common",
    "confirm": true,
    "overwrite": true,
    "languages": {
        "en": {
            "welcome_msg": "Welcome to my app!",
            "sign_in": "Sign In",
            "sign_out": "Sign out",
            "notifications": {
                "alert": "You have a new notification!"
            }
        },
        "es": {
            "welcome_msg": "¡Bienvenido a mi aplicación!",
            "sign_in": "Iniciar sesión",
            "sign_out": "Desconectar",
            "notifications": {
                "alert": "¡Tienes una nueva notificación!"
            }
        }
    }
}

Create Namespace

Adds a new namespace to your project. Namespaces affect how i18nexus organizes strings and, depending on the project's library settings, how translation JSON is exported.

This endpoint can only be used when your project is set to use namespaces.

Requires the Personal Access Token's create namespaces permission.

Parameters:

Example Request Body:

{
    "title": "common"
}

Update Namespace

Renames an existing namespace in your project.

Requires the Personal Access Token's update namespaces permission.

Parameters:

Example Request Body:

{
    "title": "common",
    "new_title": "shared"
}

Delete Namespace

Deletes an empty namespace. Namespaces with strings cannot be deleted until their strings are moved or deleted.

Requires the Personal Access Token's delete namespaces permission.

Parameters:

Example Request Body:

{
    "title": "old_namespace"
}

Limits

To prevent abuse, the i18nexus API has rate limits in place. The following limits are primarily only of concern to those teams who choose to fetch their translations at runtime in their applications. If you have a high traffic application, we recommend downloading and bundling your translations at build time in order to avoid hitting the following limits.

Request Limits (Gauged by API key)

Write Rate Limits (Gauged by API key)

The write endpoints listed above may also have their own per-endpoint rate limits. Those endpoint-specific limits are shown next to each write endpoint in this documentation and are applied in addition to the shared project resource write limit.