Locize

https://www.locize.com/docs
Admin
Locize is a modern localization management platform that bridges the gap between development and...
Tokens:86,350
Snippets:1,347
Trust Score:8.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install i18next-locize-backend

Source: https://www.locize.com/docs/guides/migrating-from/migrating-from-localazy-to-locize

Install the Locize backend plugin for i18next to enable loading translations from the Locize CDN.

```bash
npm install i18next-locize-backend
```

--------------------------------

### Install locize-cli Globally

Source: https://www.locize.com/docs/cli

Installs the locize-cli globally on your system. This command is typically run once to set up the tool.

```bash
npm install -g locize-cli
```

--------------------------------

### Example .xcstrings File Structure

Source: https://www.locize.com/docs/file-formats

This is an example of the structure of an .xcstrings file, used for iOS and macOS localization. Note that substitutions and pluralization formatting are not automatically converted.

```json
{
  "root": {
    "one" : {
      "stringUnit" : {
        "state" : "translated",
        "value" : "an iphone"
      }
    },
    "other" : {
      "stringUnit" : {
        "state" : "translated",
        "value" : "%lld iphones"
      }
    }
  }
},
"version" : "1.0"
}
```

--------------------------------

### Example: languageAdded Event

Source: https://www.locize.com/docs/integration/webhook

This is an example of the JSON payload received when a new language is added to the project.

```APIDOC
## Example: languageAdded Event

Triggered when a new language is added to the project.

```json
{
   "id":"427cc4dd-adf5-4fb8-ad8d-8508f2788fe3",
   "name":"languageAdded",
   "occurredAt":"2018-01-02T21:27:11.326Z",
   "message":"William Timberland added language de!",
   "payload":{
      "language":"de"
   },
   "meta":{
      "project":{
         "id":"23dad587-b3bf-4663-b15c-ad8d66213ac6",
         "name":"THIS PROJECT",
         "slug":"albo6dxk"
      },
      "user":{
         "id":"ab075147-c7a3-45d2-9b24-739ae2ed948a",
         "firstname":"William",
         "lastname":"Timberland"
      },
      "link":"https://www.locize.app/p/albo6dxk/v/latest"
   }
}
```
```

--------------------------------

### GET /download/{projectId}/{version}/{language}/{namespace}

Source: https://www.locize.com/docs/api

Gets a specific namespace resource for a given language and version. Requires authorization.

```APIDOC
## GET /download/{projectId}/{version}/{language}/{namespace}

### Description
Gets a specific namespace resource. Requires authorization.

### Method
GET

### Endpoint
/download/{projectId}/{version}/{language}/{namespace}
```

--------------------------------

### GET /download/{projectId}

Source: https://www.locize.com/docs/integration/api

Lists all namespace resources across all versions.

```APIDOC
## GET /download/{projectId}

### Description
Lists all namespace resources across all versions.

### Method
GET

### Endpoint
`/download/{projectId}`

### Authorization
Requires Global API Key / PAT.
```

--------------------------------

### XCString File Structure

Source: https://www.locize.com/docs/integration/file-formats

Example structure of an .xcstrings file, showing nested keys and string unit properties.

```json
{
  "one" : {
    "stringUnit" : {
      "state" : "translated",
      "value" : "an iphone"
    }
  },
  "other" : {
    "stringUnit" : {
      "state" : "translated",
      "value" : "%lld iphones"
    }
  }
}
}
            },
            "other" : {
              "stringUnit" : {
                "state" : "translated",
                "value" : "%lld devices"
              }
            }
          }
        }
      }
    }
  },
  "version" : "1.0"
}
```

--------------------------------

### Start Locize Standalone with Custom Project Configuration

Source: https://www.locize.com/docs/incontext

Initiate the Locize standalone editor with specific project ID and version details.

```javascript
startStandalone({
  projectId: 'your-project-id',
  version: 'latest'
})
```

--------------------------------

### GET /download/{projectId}

Source: https://www.locize.com/docs/api

Lists all namespace resources across all versions. Requires authorization.

```APIDOC
## GET /download/{projectId}

### Description
Lists all namespace resources (all versions). Requires authorization.

### Method
GET

### Endpoint
/download/{projectId}
```

--------------------------------

### GET /download/{projectId}/{version}

Source: https://www.locize.com/docs/integration/api

Lists all namespace resources for a specific version.

```APIDOC
## GET /download/{projectId}/{version}

### Description
Lists all namespace resources for a specific version.

### Method
GET

### Endpoint
`/download/{projectId}/{version}`

### Authorization
Requires Global API Key / PAT.
```

--------------------------------

### GET /download/{projectId}/{version}/{language}

Source: https://www.locize.com/docs/api

Lists all namespace resources for a specific language and version. Requires authorization.

```APIDOC
## GET /download/{projectId}/{version}/{language}

### Description
Lists all namespace resources for a language. Requires authorization.

### Method
GET

### Endpoint
/download/{projectId}/{version}/{language}
```

--------------------------------

### GET /download/{projectId}/{version}/{language}

Source: https://www.locize.com/docs/integration/api

Lists all namespace resources for a specific language within a version.

```APIDOC
## GET /download/{projectId}/{version}/{language}

### Description
Lists all namespace resources for a specific language within a version.

### Method
GET

### Endpoint
`/download/{projectId}/{version}/{language}`

### Authorization
Requires Global API Key / PAT.
```

--------------------------------

### Flat JSON Key Example

Source: https://www.locize.com/docs/how-do-i-open-and-edit-json-files

Example of a flat JSON structure where keys are dot-separated strings.

```json
"label.cancel": "Cancel"
```

--------------------------------

### GET /{projectId}/{version}/{language}/{namespace}

Source: https://www.locize.com/docs/api

Fetches namespace resources from the CDN.

```APIDOC
## GET /{projectId}/{version}/{language}/{namespace}

### Description
Fetches namespace resources from the CDN.

### Method
GET

### Endpoint
/{projectId}/{version}/{language}/{namespace}
```

--------------------------------

### GET /download/{projectId}/{version}

Source: https://www.locize.com/docs/api

Lists all namespace resources for a specific version. Requires authorization.

```APIDOC
## GET /download/{projectId}/{version}

### Description
Lists all namespace resources for a version. Requires authorization.

### Method
GET

### Endpoint
/download/{projectId}/{version}
```

--------------------------------

### GET {projectId}/{version}/{language}/{namespace}

Source: https://www.locize.com/docs/integration/api

Fetches namespace resources from the CDN.

```APIDOC
## GET {projectId}/{version}/{language}/{namespace}

### Description
Fetches namespace resources from the CDN.

### Method
GET

### Endpoint
`/{projectId}/{version}/{language}/{namespace}`
```

--------------------------------

### Fluent Localization Syntax

Source: https://www.locize.com/docs/file-formats

Example of Fluent syntax for defining localized strings with pluralization and variable substitution.

```ftl
emails =
  { $unreadEmails ->
    [one] You have one unread email.
   *[other] You have { $unreadEmails } unread emails.
  }
-brand-name =
  {
   *[nominative] Firefox
    [accusative] Firefoxa
  }
-another-term = another term
app-title = { -brand-name }
restart-app = Zrestartuj { -brand-name[accusative] }.
# Note: { $title } is a placeholder for the title of the web page
# captured in the screenshot. The default, for pages without titles,
is
# creating-page-title-default.
login = Predefined value
  .placeholder = example@email.com
  .aria-label = Login input value
  .title = Type your login email
logout = Logout
```

--------------------------------

### GET /private/{projectId}/{version}/{language}/{namespace}

Source: https://www.locize.com/docs/api

Fetches private namespace resources from the CDN. Requires authorization.

```APIDOC
## GET /private/{projectId}/{version}/{language}/{namespace}

### Description
Fetches private namespace resources from the CDN. Requires authorization.

### Method
GET

### Endpoint
/private/{projectId}/{version}/{language}/{namespace}
```

--------------------------------

### Gettext PO File Example

Source: https://www.locize.com/docs/file-formats

Standard Gettext PO file format for storing translations. Includes metadata and message strings.

```gettext
msgid ""
msgstr ""
"Project-Id-Version: Locize: My project - translations\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1)\n"
"POT-Creation-Date: 2017-07-14T22:26:46.631Z\n"
"PO-Revision-Date: 2017-07-14T22:26:46.631Z\n"
"Language: it\n"
msgid "title"
msgstr "La soluzione migliore per il miglior cliente!"
msgid "description"
msgstr ""
"Questa è una descrizione di esempio per mostrare come funziona la traduzione "
"in un file .po."
```

--------------------------------

### Vanilla JavaScript Locize Event Handling and Initialization

Source: https://www.locize.com/docs/incontext

Handle Locize save events and start the standalone editor using global JavaScript variables in vanilla projects.

```javascript
window.locizeSavedHandler = res => {
  res.updated.forEach(item => {
    const { lng, ns, key, data } = item
    // load the translations somewhere...
    // and maybe rerender your UI
  })
}

window.locizeStartStandalone()
```

--------------------------------

### Standalone Locize Editor Setup without i18next

Source: https://www.locize.com/docs/incontext

Set up the Locize editor for standalone use without i18next. Includes optional saved handler and language switching.

```javascript
import { addLocizeSavedHandler, startStandalone, setEditorLng } from 'locize'

// optional: handle saved translations
addLocizeSavedHandler(res => {
  res.updated.forEach(item => {
    const { lng, ns, key, data } = item
    // load the translations somewhere...
    // and maybe rerender your UI
  })
})

// start the editor
startStandalone()

// switch language in the editor
setEditorLng(lng)
```

--------------------------------

### Next.js Pages Router Caching with Filesystem

Source: https://www.locize.com/docs/alternative-caching-with-i18next

Configure i18next for Next.js Pages Router (v15/v16) to use a chained backend for filesystem caching. This example shows the setup for next-i18next.config.js.

```javascript
const ChainedBackend = require('i18next-chained-backend')
const FSBackend = require('i18next-fs-backend/cjs')
const LocizeBackend = require('i18next-locize-backend/cjs')

module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'de'],
  },
  backend: {
    backends: [FSBackend, LocizeBackend],
    backendOptions: [{
      loadPath: './public/locales_cache/{{lng}}/{{ns}}.json',
      addPath: './public/locales_cache/{{lng}}/{{ns}}.json',
      expirationTime: 7 * 24 * 60 * 60 * 1000 // 7 days
    }, {
      projectId: 'd3b405cf-2532-46ae-adb8-99e88d876733'
    }]
  },
  use: [ChainedBackend],
  ns: ['common', 'footer', 'second-page'],
  serializeConfig: false,
}

```

--------------------------------

### POST /create/{projectId}/{version}/{namespace}

Source: https://www.locize.com/docs/integration/api

Creates a new namespace in the reference language.

```APIDOC
## POST /create/{projectId}/{version}/{namespace}

### Description
Creates a new namespace in the reference language.

### Method
POST

### Endpoint
`/create/{projectId}/{version}/{namespace}`

### Authorization
Requires Global API Key / PAT.
```

--------------------------------

### Create a new tenant project

Source: https://www.locize.com/docs/api

Creates a new tenant project.

```APIDOC
## POST /tenant/create/{projectId}

### Description
Create a new tenant project.

### Method
POST

### Endpoint
/tenant/create/{projectId}
```

--------------------------------

### Nested JSON Structure Example

Source: https://www.locize.com/docs/how-do-i-open-and-edit-json-files

Example of a nested JSON structure using object nesting to organize keys.

```json
{
  "label": {
    "cancel": "Cancel"
  }
}
```

--------------------------------

### POST /create/{projectId}/{version}/{namespace}

Source: https://www.locize.com/docs/api

Creates a new namespace in the reference language. Requires authorization.

```APIDOC
## POST /create/{projectId}/{version}/{namespace}

### Description
Creates a new namespace in the reference language. Requires authorization.

### Method
POST

### Endpoint
/create/{projectId}/{version}/{namespace}
```

--------------------------------

### Get Project Statistics

Source: https://www.locize.com/docs/api

Retrieves overall statistics for a specific project.

```APIDOC
## GET /stats/project/{projectId}

### Description
Retrieves statistics for a given project.

### Method
GET

### Endpoint
/stats/project/{projectId}
```

--------------------------------

### Integrate Locize with Vue-I18n (Vue v3)

Source: https://www.locize.com/docs/instrumenting-your-code

This example shows how to initialize Locize and create a Vue-I18n instance, setting the locale and fallback locale based on Locize's settings. It also demonstrates loading all messages asynchronously.

```javascript
import { createI18n } from 'vue-i18n'
import Locizer from 'locizer'
locizer.init({
  projectId: 'project-id'
});
export const i18n = createI18n({
  locale: Locizer.lng, // set locale
  fallbackLocale: 'en' // set fallback locale
  // If you need to specify other options, you can set other options
  // ...
});
// called from within setup hook in App.vue
export const loadMessagesPromise = new Promise((resolve, reject) => {
  Locizer.loadAll('messages', (err, messages) => {
    if (err) return reject(err);
    Object.keys(messages).forEach((l) => {
      i18n.global.setLocaleMessage(l, messages[l])
    });
    resolve(messages);
  })
})
```

--------------------------------

### POST /create/{projectId}/{version}/{language}/{namespace}

Source: https://www.locize.com/docs/integration/api

Creates a new namespace in a specific language.

```APIDOC
## POST /create/{projectId}/{version}/{language}/{namespace}

### Description
Creates a new namespace in a specific language.

### Method
POST

### Endpoint
`/create/{projectId}/{version}/{language}/{namespace}`

### Authorization
Requires Global API Key / PAT.
```

--------------------------------

### GET /languages/{projectId}

Source: https://www.locize.com/docs/api

Fetches the available languages for a given project.

```APIDOC
## GET /languages/{projectId}

### Description
Fetches the available languages for a given project.

### Method
GET

### Endpoint
/languages/{projectId}
```

--------------------------------

### POST /create/{projectId}/{version}/{language}/{namespace}

Source: https://www.locize.com/docs/api

Creates a new namespace in a specific language. Requires authorization.

```APIDOC
## POST /create/{projectId}/{version}/{language}/{namespace}

### Description
Creates a new namespace in a specific language. Requires authorization.

### Method
POST

### Endpoint
/create/{projectId}/{version}/{language}/{namespace}
```

--------------------------------

### Get Async Job Status

Source: https://www.locize.com/docs/api

Retrieves the status of an asynchronous job associated with a project.

```APIDOC
## GET /jobs/{projectId}/{jobId}

### Description
Fetches the status of an asynchronous job.

### Method
GET

### Endpoint
/jobs/{projectId}/{jobId}
```

--------------------------------

### GET /pull/{projectId}/{version}/{language}/{namespace}

Source: https://www.locize.com/docs/integration/api

Fetches or filters unpublished namespace resources.

```APIDOC
## GET /pull/{projectId}/{version}/{language}/{namespace}

### Description
Fetches or filters unpublished namespace resources.

### Method
GET

### Endpoint
`/pull/{projectId}/{version}/{language}/{namespace}`

### Authorization
Requires Global API Key / PAT.
```

--------------------------------

### Migrate Existing Translations using Locize CLI

Source: https://www.locize.com/docs/migrating-an-i18next-project

Upload your current i18next translation files to your Locize project using the Locize CLI. Replace `<your-api-key>` and `<your-project-id>` with your specific credentials and specify the path to your translation files.

```bash
locize migrate --api-key <your-api-key> --project-id <your-project-id> --path ./public/locales

```

--------------------------------

### Get User Translation Statistics

Source: https://www.locize.com/docs/api

Retrieves statistics related to user translations for a specific project and user.

```APIDOC
## GET /stats/user-translation/{projectId}/{userId}

### Description
Retrieves statistics for user translations within a project.

### Method
GET

### Endpoint
/stats/user-translation/{projectId}/{userId}
```

--------------------------------

### SimpleLocalize Configuration

Source: https://www.locize.com/docs/guides/migrating-from/migrating-from-simplelocalize-to-locize

This is the previous configuration used with SimpleLocalize, showing the `loadPath` format.

```javascript
import i18n from 'i18next'
import Backend from 'i18next-http-backend'
import { initReactI18next } from 'react-i18next'

const cdnBaseUrl = 'https://cdn.simplelocalize.io'
const projectToken = 'YOUR_TOKEN'
const environment = '_latest'

i18n
  .use(Backend)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    backend: {
      loadPath: `${cdnBaseUrl}/${projectToken}/${environment}/{{lng}}/{{ns}}`
    }
  })
```

--------------------------------

### GET /pull/{projectId}/{version}/{language}/{namespace}

Source: https://www.locize.com/docs/api

Fetches or filters unpublished namespace resources. Requires authorization.

```APIDOC
## GET /pull/{projectId}/{version}/{language}/{namespace}

### Description
Fetches or filters the (unpublished) namespace resources. Requires authorization.

### Method
GET

### Endpoint
/pull/{projectId}/{version}/{language}/{namespace}
```

--------------------------------

### Server-Side Fallback with Filesystem Backend

Source: https://www.locize.com/docs/backend-fallback

Configure i18next for server-side applications to use the filesystem backend as a fallback. This complements the primary backend (e.g., Locize) by providing local translation files.

```javascript
import i18next from "i18next";
import ChainedBackend from "i18next-chained-backend";
import LocizeBackend from "i18next-locize-backend";
import FsBackend from "i18next-fs-backend";
i18next
  .use(ChainedBackend)
  .init({
    fallbackLng: "en",
    // ... your i18next config
    backend: {
      backends: [
        LocizeBackend,
        FsBackend
      ],
      backendOptions: [{
        projectId: "[PROJECTID]",
        apiKey: "[APIKEY]",
        version: "[VERSION]"
      }, {
        loadPath: './locales_cache/{{lng}}/{{ns}}.json'
      }]
    }
  });
```

--------------------------------

### Migrate translations using i18next-cli

Source: https://www.locize.com/docs/guides/migrating-from/migrating-from-simplelocalize-to-locize

Upload all namespaces and languages to your Locize project using the i18next-cli. This command preserves keys and values exactly. Ensure you have your Locize Project ID and API Key.

```bash
npx i18next-cli locize-migrate \
  --project-id YOUR_LOCIZE_PROJECT_ID \
  --api-key YOUR_LOCIZE_API_KEY \
  --path ./translations
```
Tokens:
Raw