Phrases#

Phrases are the core translation units in Multilocale. Each phrase has a key, a value, and a language.

Phrase Object#

{
  "_id": "507f1f77bcf86cd799439011",
  "key": "welcome_message",
  "value": "Welcome to our app!",
  "language": "en",
  "organizationId": "507f1f77bcf86cd799439012",
  "projects": ["my-app"],
  "projectsIds": ["507f1f77bcf86cd799439013"],
  "googleTranslate": false,
  "creationTime": "2024-01-15T10:30:00.000Z",
  "lastEditTime": "2024-01-15T10:30:00.000Z"
}

List Phrases#

Retrieve phrases matching the given filters.

GET /api/phrases

Authentication: Token or organizationId query parameter

Query Parameters#

Parameter	Type	Description
`organizationId`	`string`	Filter by organization (alternative to token auth)
`key`	`string`	Filter by exact key (URL-encoded)
`language`	`string`	Filter by language code
`project`	`string`	Filter by project name
`fields`	`string`	Comma-separated list of fields to return
`pagination`	`cursor`	Return a stable cursor-page envelope
`cursor`	`string`	Opaque `nextCursor` from the preceding page
`limit`	`number`	Page size; cursor pages default to 100 (max 2001)

Example#

# Get all English phrases for a project
curl "https://api.multilocale.com/api/phrases?project=my-app&language=en" \
  -H "Authorization: Token <base64-token>"

# Get specific fields only
curl "https://api.multilocale.com/api/phrases?project=my-app&fields=key,value,language" \
  -H "Authorization: Token <base64-token>"

# Public access with organizationId
curl "https://api.multilocale.com/api/phrases?organizationId=abc123&project=my-app&language=en"

Cursor pagination#

Use cursor pagination for a stable traversal that does not become slower at large offsets. The first request sets pagination=cursor; each subsequent request sends back the preceding response's opaque nextCursor.

curl "https://api.multilocale.com/api/v1/phrases?project=my-app&pagination=cursor&limit=100" \
  -H "Authorization: Basic <base64-api-key-secret>"

curl "https://api.multilocale.com/api/v1/phrases?project=my-app&pagination=cursor&limit=100&cursor=<nextCursor>" \
  -H "Authorization: Basic <base64-api-key-secret>"

Cursor pages use stable ascending phrase-id ordering and return:

{
  "items": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "key": "welcome_message",
      "value": "Welcome!",
      "language": "en"
    }
  ],
  "nextCursor": "NTA3ZjFmNzd..."
}

nextCursor is null on the final page. Treat it as opaque. Offset pagination and the legacy array response remain available when pagination=cursor is not set.

Response#

[
  {
    "key": "welcome_message",
    "value": "Welcome!",
    "language": "en"
  },
  {
    "key": "goodbye",
    "value": "Goodbye!",
    "language": "en"
  }
]

Create Phrases#

Create one or more phrases.

POST /api/phrases

Authentication: Token required

Body#

A single phrase object or an array of phrase objects:

[
  {
    "_id": "unique-id-1",
    "key": "welcome_message",
    "value": "Welcome!",
    "language": "en",
    "projects": ["my-app"],
    "projectsIds": ["project-id"]
  },
  {
    "_id": "unique-id-2",
    "key": "welcome_message",
    "value": "Bienvenido!",
    "language": "es",
    "projects": ["my-app"],
    "projectsIds": ["project-id"]
  }
]

Response#

Returns the created phrase(s) in the same shape as the input (single object or array).

Batch upsert phrases#

Use the explicit batch route when an integration always sends multiple phrase rows. It accepts the same array body as POST /api/v1/phrases and returns the upserted rows in input order.

POST /api/v1/phrases/batch

curl -X POST "https://api.multilocale.com/api/v1/phrases/batch" \
  -H "Authorization: Basic <base64-api-key-secret>" \
  -H "Content-Type: application/json" \
  --data '[
    {
      "key": "welcome_message",
      "value": "Welcome!",
      "language": "en",
      "projects": ["my-app"]
    },
    {
      "key": "welcome_message",
      "value": "Bienvenido!",
      "language": "es",
      "projects": ["my-app"]
    }
  ]'

The API applies authentication, project scope, and rate limiting once for the request. Each phrase still produces its own phrase.created or phrase.updated webhook event.

Update a Phrase#

Update an existing phrase.

PUT /api/phrases/:phraseId

Authentication: Token required

Body#

{
  "_id": "507f1f77bcf86cd799439011",
  "key": "welcome_message",
  "value": "Welcome to our updated app!",
  "language": "en"
}

Response#

Returns the updated phrase object.

Delete Phrases#

Delete all phrases matching a key and project.

DELETE /api/phrases

Authentication: Token required

Query Parameters#

Parameter	Type	Required	Description
`key`	`string`	Yes	The phrase key (URL-encoded)
`project`	`string`	Yes	The project name

Example#

curl -X DELETE "https://api.multilocale.com/api/phrases?key=old_key&project=my-app" \
  -H "Authorization: Token <base64-token>"

Response#

Returns an array of the deleted phrases, or 404 if no matching phrases were found.