
Learn how to improve your localization workflow with SimpleLocalize CLI. Use CLI to download or upload translations or translation keys. Moreover, you can use 'extract' command to find translation keys in project files.

![get started with localization cli tool](/docs/get-started.png)

## Installation

```shell
curl -s https://get.simplelocalize.io/install | bash
```

## Usage

```properties
simplelocalize [COMMAND] --apiKey <PROJECT_API_KEY> rest of parameters...
```

## SimpleLocalize CLI commands

- [`upload`](/docs/cli/upload-translations) - upload translations files
- [`download`](/docs/cli/download-translations) - download translations files
- [`extract`](/docs/cli/i18n-keys-extraction) - find translations and translation keys in project sources


## SimpleLocalize CLI Authorization

Each CLI commands needs to be authorized with `--apiKey`. 
API Key can be found in 'Integration' tab in your project. See the screen below.

> You should never expose this token to the public.

![SimpleLocalize API Key](/docs/simplelocalize-api-key.png)


Get started


![simplelocalize integration options](/docs/simplelocalize-options.png)

SimpleLocalize is a simple and user-friendly translation management solution. Can be used in different ways, you can choose between:

- [**Host your translation files**](/docs/general/translation-hosting/): publish translations and access them using CDN,
- [**Upload translations with CLI**](/docs/cli/upload-translations/): upload translation files from your project files,
- [**Download translations with CLI**](/docs/cli/download-translations/): download translations to your project files,
- [**Add webhook**](/docs//general/webooks/): get server notification when somebody publishes changes or exports a file,
- [**Get started with REST API**](/docs/cli/get-started/): use our free REST API to manage translations right away.

> If you have any questions or suggestions, let me know at [jakub@simplelocalize.io](mailto:jakub@simplelocalize.io)

## Happy coding!


Introduction


Invite your team to the SimpleLocalize. Work together on project translations. Send e-mail invitation to your colleagues
in 'Contributors' tab. Type user e-mail, and we will send invitation automatically. SimpleLocalize will create account
for your teammate. In the e-mail we will send a link where the invited person can set up its password to log in.

Collaborative features are available on every plan.

![shareable links](/docs/project-sharing.jpg)

## Project roles

### 🏡 Project owner role

One per project. Only project owner can delete a project.
If you want to change project ownership, then please contact support.

### 👑 Administrator role

Every project can have many administrators. Administrator rights are equal with a project owner role. The only difference between those two roles is that Administrator
cannot delete the project.

### 🌍 Translator role

Every project can have many translators. Translator don't have access to `Integrations`, `Rollbacks`, `Members`, `Other`
tabs. Translator have access only to `Translations`, `Languages`, `Data`, and `Activity` tabs.

## 📨 Send e-mail invitation

Open translation project and go to '__Contributors__' tab. Use '__Invite contributor__' button on top right side.
SimpleLocalize will send e-mail with invitation automatically. Invitation e-mail will contain an invitation link which will
redirect recipient to create account page, or the invitation page where he/she can accept invitation. After that invited
person can sign in to the account. Project will be available on the projects list in a dashboard.

> Invitation links are valid for 7 days from receiving. After that project administrator or project owner can send invitation once again.

## 🔗 Shareable links

Shareable links are an easy way of inviting more people to a project.

![shareable links](/docs/shareable-links.png)

In the '__Contributors__' tab you can find 2 different links. One is for inviting [project administrators](#administrator-role) and the second one is for inviting [translators](#translator-role).

Person who would like to use the invitation link must create an account first in SimpleLocalize. If you would like to invite somebody who is not 
a part of your team on daily basis, then you can use [e-mail invitations](#send-e-mail-invitation).

Shareable links can be regenerated in case of posting them in the public place. If you regenerated them by accident, and you want to revert this process, then please contact us. We can fix it. 😄


Project sharing



The advancements in the field of AI have led to the development of a tool that can translate text from one language to another in a matter of seconds. 
Machine translation options are a great replacement for expensive translators. 

Even though this tool is very helpful, there are some inaccuracies when translating from one language to another.

Available translation services in SimpleLocalize:
- [Google Translate](https://translate.google.com) is the most popular translation service in the world. It supports more than 100 languages and can translate entire sentences at a time for quick comprehension.
- [DeepL translator](https://www.deepl.com/translator) is the only machine translation engine that supports features like auto-detecting text languages, translating content with vector graphics and formatting, machine learning-driven translations that are more accurate than any other system on the market. 

## How to use auto translation?

In order to auto-translate your texts go to 'Languages' tab and select option 'Start auto translation' next 
to the language you want to get translated.

![languages tab and auto translate option](/docs/my-languages-auto-translation.png)

> The 'Start auto translation' button won't show up, if 100% language content is translated.


Once you click the 'Start auto translation' button, you will see a popup with auto translation options.

![start auto translation popup](/docs/start-auto-translation-popup.png)

Here you can choose which translation service would you like to use and into which language SimpleLocalize should translate texts. 
Source language is selected automatically based on the translation service recommendations to provide the best results.

Available translation services: 
- [Google Translate](https://translate.google.com) - provides more languages, it cannot preserve translation format, it may offer inaccurate translations.
- [DeepL](https://www.deepl.com/translator) - provides more accurate translations and is able to preserve format. The format preserving is useful when you use HTML or any other markdown in translations.

Next, click 'Start translation' button. SimpleLocalize will now run auto-translation process in background, so you can close the window. Usually, auto-translation takes only a couple of seconds. 
Progress of auto translation process is showed in the 'Languages' tab and the final result is logged in the 'Activity' tab.

![finished auto translation activity](/docs/finished-auto-translation-activity.png)


### How to exclude text from auto translation

To exclude texts from being translated by machine translations you can use brackets `{` and `}` to mark words or whole sentences and `EXCLUDE_VARIABLES` option from auto-translation popup menu.

![do not translate variables](/docs/auto-translation-options.png)

Texts in brackets will be omitted in translation by the translation service. Below you can see the example usage of marking texts in SimpleLocalize translation editor.
![texts excluded from translation](/docs/variables-in-texts.png)


Auto translation


Check the best practises on choosing language keys in your project. Learn what are the options on choosing language keys standard. 
Every translation project created in SimpleLocalize can have **unlimited number of languages**.

![language keys good practised](/docs/language-keys.png)

In SimpleLocalize every language contains '__language key__' for a developer and export proposed, and '__language name__' which can be treated as user-friendly display name.
We don't restrict you to use any specific format for '__language keys__', but it's worth to consider using some standardized structure. 

## How to add a new language

- Open translation project in web application.
- Go to '__Languages__' tab  
- Add new language by clicking '__Add language__' button on top right side
- Put __language key__ and __language name__
- Click '__Add language__'
- Done! 🎉

## Language icons

Flag icons are displayed automatically based on language keys. 
SimpleLocalize uses [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) standard with 'Alpha-2' notation. 
The 'Alpha-2' means that we use only 2-letter country codes. The flag will show up regardless letter case. For example:
- `es_MX` - shows Mexico flag
- `es_ES` - shows Spanish flag
- `es_es` - shows Spanish flag
- `es` - shows Spanish flag

![Example country flags based on ISO-3166-1](/docs/showing-country-flags-based-on-iso-3166-1.png)

There are a few exceptions made in showing country flags:
- `zh_hans` or `zh_hant` will show the Chinese flag.
- A language key which starts from `en` will show the Great Britain flag.

## i18n and l10n standards

- **ISO-3166-1 Alpha-2**: Ready to use https://github.com/simplelocalize/iso-3166
- **ISO-639**: Ready to use https://github.com/simplelocalize/iso-639
- [**IETF language tag**](https://en.wikipedia.org/wiki/IETF_language_tag)
- [**ISO-15924**](https://en.wikipedia.org/wiki/ISO_15924)

Read more about [ISO-3166](https://en.wikipedia.org/wiki/ISO_3166-1) and [ISO-639](https://en.wikipedia.org/wiki/ISO_639)


Language keys


Host your translations as JSON files on our free of charge hosting with super-fast CDN access. 
It allows you to fetch translations from anywhere with lightning speed in JSON and use it without extra configuration in any project.

![how translations hosting works](/docs/translations-hosting-schema.jpg)

Every time you publish changes something magical is happening. SimpleLocalize puts the newest version
of your translations from the web translation editor into our CDN in multiple formats with **super-fast access speed!**

## How to publish translations

![how to publish translations](/docs/change-translations.gif)

## Set up a default language

In order to always provide a translation for a language which is not yet fully translated, you can set up a default language.
To set up a default language, head to the 'Languages' tab and click 'Edit' on the language which you want to set up as
default. Then, check option 'Use as a default language' and click save. 
Re-deploy your translations using 'Publish' button to see the changes on the CDN.

## How to access hosted translations

Access to the SimpleLocalize CDN does not require authorization. Thanks to that you can integrate it with
your web application or any kind of application. Access to CDN content looks same like to a REST API.

### <span class="badge badge-primary">GET</span> Get all translations

```
https://cdn.simplelocalize.io/:projectToken/_latest/_index
```

### <span class="badge badge-primary">GET</span> Get translations by language key
```
https://cdn.simplelocalize.io/:projectToken/_latest/:languageKey
```

### <span class="badge badge-primary">GET</span> Get languages
```
https://cdn.simplelocalize.io/:projectToken/_latest/_languages
```

All available CDN endpoints can be found in '[Read translations](/docs/api/read-translations)' section.


## How to revert translations to previous state? 

Open the 'Rollbacks' tab and click 'Publish' on the version which you want to publish. You can also browse `_index` file for each version using the 'Browse' button.

![translation rollback menu](/docs/translation-rollback-menu.png)

Please notice that the 'Publish' button in the 'Rollbacks' tab will revert translations to the 'Latest' environment. 
If you want to push translations to the 'Production' environment, then please head to the 'Hosting' tab and use button 
'Publish' to copy the 'Latest' environment to the 'Production'.

![how to rollback translations](/docs/how-to-rollback-translations.jpg)

Resources:

- [Integrate i18next with SimpleLocalize CDN](/docs/integrations/i18next)
- [Integrate FormatJS with SimpleLocalize CDN](/docs/integrations/format-js)





Translation hosting


Webhooks allow external services to be notified when certain events happen. When the specified events happen, we’ll send a POST request to each of the URLs you provide.

![translation management system webhooks](/docs/webhooks.png)

Webhook payload

```json
{
  "trigger": "AUTO_TRANSLATION_SUCCESS",
  "projectToken": "<YOUR_PROJECT_TOKEN>",
  "jobId": "<JOB_ID>"
}
```

Table with available `trigger` field values

trigger value | Event description
--- | ---
`PUBLICATION` | Translations publication via API or WEB
`CHANGE` | Every saved translation change via API, WEB or CLI
`REVERT` | On reverted translations via WEB
`IMPORT` | On every file import via WEB, API or CLI
`EXPORT` | On every file export via WEB, API or CLI
`EXTRACTION` | On translations CLI extraction via CLI
`AUTO_TRANSLATION_SUCCESS` | On every succeeded auto-translation job started via WEB, API or CLI. `jobId` will contain finished job identifier
`AUTO_TRANSLATION_FAILED` | On every failed auto-translation job started via WEB, API or CLI. `jobId` will contain failed job identifier

Webhook URL cannot contain IP addresses, localhost domain, or SimpleLocalize API. It must be a valid URL. URL must respond to a HEAD request to be added.


Webhooks


## Quick Start

Learn how to extract localization key from Android project to local file. This guide will show you how to configure CLI
to find localization keys in your project files.

If you already have extracted translation keys or translated messages in your `strings.xml` files, then go to
page [Android XML to upload your data first](/docs/file-formats/android-xml).

Resources:

- [Android String Resource](https://developer.android.com/guide/topics/resources/string-resource)

## Installation

Install SimpleLocalize CLI

```shell
curl -s https://get.simplelocalize.io/install | bash
```

Problems with CLI? See [troubleshooting section](/docs/cli/troubleshooting).

## Extract translation keys

SimpleLocalize CLI will try to find translation key usages in `.java` and `.kt` files. After that translation keys will
be automatically uploaded to the translation editor.

```properties
simplelocalize extract --apiKey <PROJECT_KEY> \
  --projectType google/android \
  --searchDir ./src
```

## Translate messages

Now you can translate the messages or share the project with professional translators.

![android xml translation management](/docs/translation-editor.png)

## Download translations

```properties
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat androd \
  --downloadPath ./resources/values-{lang}/strings.xml
```


Android


## Quick Start

Check how to find all translation keys in iOS/macOS project. Learn how to extract localization key from Android project
to local file. This guid will show you how to configure CLI to find localization keys in your project files.

If you already have extracted translation keys or translated messages in your `strings.xml` files, then go to
page [Localizable Strings to upload your data first](/docs/file-formats/localizable-strings).

Resources:

- [Maintaining your own Strings files](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPInternational/MaintaingYourOwnStringsFiles/MaintaingYourOwnStringsFiles.html) (
  source: developer.apple.com)
- [Localizing Your App](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPInternational/LocalizingYourApp/LocalizingYourApp.html#//apple_ref/doc/uid/10000171i-CH5-SW1) (
  source: developer.apple.com)

## Installation

Install SimpleLocalize CLI

```shell
curl -s https://get.simplelocalize.io/install | bash
```

Problems with CLI? See [troubleshooting section](/docs/cli/troubleshooting).

## Find keys

Use CLI to find all translation keys used in project files.

```properties
simplelocalize extract --apiKey <PROJECT_KEY> \
  --projectType apple/ios-macos \
  --searchDir ./src
```

## Translate messages

![localizable strings translation editor](/docs/translation-editor.png)

## Download files

Download ready to use files for your project by running download command.

```properties
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadPath ./Resources/Localization/{lang}.lproj/Localizable.strings \
  --downloadFormat localizable-strings
```





iOS & macOS


![i18next: changing translations in realtime](/docs/hosting-translations.jpg)

In this article, you will learn how to configure i18next to server-side translations using `i18next-http-backend` library. Additionally, I will show you how to automatically create
translation keys with default translation in SimpleLocalize translation editor.

## Install dependencies

```bash
# Using NPM
npm install --save react-i18next i18next i18next-http-backend i18next-browser-languagedetector axios

# Using yarn
yarn add react-i18next i18next i18next-http-backend i18next-browser-languagedetector axios
```

## Configure i18next

Create `i18n.ts` file with i18next configuration. This file will be imported in `index.ts`.

```tsx
import i18n from 'i18next'
import Backend from 'i18next-http-backend'
import LanguageDetector from 'i18next-browser-languagedetector'
import { initReactI18next } from 'react-i18next'
import axios from "axios";

const fallbackLanguage = 'en'

const projectToken = ""; // YOUR PROJECT TOKEN
const apiKey = ""; // YOUR API KEY

const loadPath = `https://cdn.simplelocalize.io/${projectToken}/_latest/{{lng}}`;
const addMissingTranslationsEndpoint = `https://api.simplelocalize.io/api/v1/translations`;

i18n
  .use(Backend)
  .use(LanguageDetector)
  .use (initReactI18next)
  .init({
    fallbackLng: fallbackLanguage,
    backend: {
      loadPath: loadPath
    },
    saveMissing: true,
    missingKeyHandler: (lngs, ns, key, fallbackValue) => {
      // optional step
      const configuration = {
        headers: {
          'X-SimpleLocalize-Token': apiKey
        }
      };

      const requestBody = {
        content: [
          {
            key: key,
            language: fallbackLanguage,
            text: fallbackValue
          }
        ]
      }
      axios.post(addMissingTranslationsEndpoint, requestBody, configuration)
    }
  })

export default i18n;
```

## Configure i18next in application

Import `i18n.ts` file in `index.ts` by adding `import './i18n';` Whole `index.ts` file should look like this:

```tsx
import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import './i18n'; // import i18next configuration (!!)

ReactDOM.render (
  <React.StrictMode>
    <Suspense fallback={<div>Loading...</div>}>
        <App />
    </Suspense>
  </React.StrictMode>,
  document.getElementById('root')
);
```

## Example usage

```tsx
import React from "react";
import { useTranslation } from "react-i18next";

function App() {
  const { t, i18n } = useTranslation();
  return (
        <div>
          <p>
            {t("USE_BUTTONS_BELOW")}
          </p>
          <button onClick={() => i18n.changeLanguage("en")}>English</button>
          <button onClick={() => i18n.changeLanguage("es")}>Spanish</button>
        </div>
  );
}

export default App;
```

Use `t` function to get translation from given translation key
```jsx
t("USE_BUTTONS_BELOW")
```

Switch languages with `i18n.changeLanguage(language)`. `i18n` ibject comes from React Hook called `useTranslations()`;

## Translate and publish changes

Now, your users will see the updated translation every time you click 'Publish' button in the translation editor!

![i18next translation management](/docs/change-translations.gif)

More resources:

- [i18next and React application localization in 3 steps](/blog/posts/i18next-reactjs-localization/)
- [Example i18next project on GitHub](https://github.com/simplelocalize/simplelocalize-i18next)


i18next


![FormatJS: changing translations in realtime](/docs/hosting-translations.jpg)

Here you will learn how to configure FormatJS with [translation hosting feature](/docs/general/translation-hosting). Translation
hosting allow your users to see translated messages right away when you click the 'Publish' button in the translation
editor. Later, you will learn how to use `<FormattedMessage/>` and `intl` object.

## Translation live updates

Let's start with learning how to integrate translation hosting feature to update translations right away when you click 'Publish' in
the translation editor and a general configuration.

### Install dependencies

Add `react-intl` library to your React app project.

```bash
# Using NPM
npm i -S react react-intl

# Using yarn
yarn add react react-intl
```

### Get a project token

[Create a project in SimpleLocalize](https://simplelocalize.io/register/), and get your project token from the 'Integrations' tab. 
You will need the token to fetch translations from the server.

![simplelocalize project token location](/docs/where-project-token-is-located.png)

### react-intl configuration
Create configuration like below:

```jsx
import React from "react";
import {IntlProvider} from 'react-intl'
import LanguageContext from "./LanguageContext";

class SimpleLocalize extends React.Component {

  constructor(props) {
    super(props);
    this.state = {
      messages: undefined,
      language: "en"
    };
  }

  componentDidMount() {
    this.setupLanguageMessages(this.state.language);
  }

  setupLanguageMessages = (language) => {
    const projectToken = "<YOUR_PROJECT_TOKEN>";
    const translationsUrl = `https://cdn.simplelocalize.io/${projectToken}/_latest/${language}`;
    return fetch(translationsUrl)
      .then((data) => data.json())
      .then((messages) => this.setState({language, messages}));
  };

  render() {
    return (
      <LanguageContext.Provider
        value={{
          changeLanguage: (language) => this.setupLanguageMessages(language)
        }}>
        <IntlProvider
          locale={this.state.language}
          messages={this.state.messages}>
          {this.state.messages ? this.props.children : null}
        </IntlProvider>
      </LanguageContext.Provider>
    )
  }
}

export default SimpleLocalize;
```

### Wrap main component

Wrap your main application component with the created `SimpleLocalize` component to provide translations for React application.

```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import SimpleLocalize from "./SimpleLocalize";

ReactDOM.render(
    <SimpleLocalize>
      <App/>
    </SimpleLocalize>,
  document.getElementById('root')
);
```

### FormattedMessage usage

```jsx
<FormattedMessage id="YOUR_TRANSLATION_KEY"/>
```

React will convert the `FormattedMessage` tag into a `span` tag and put concrete translation into it. You can also use `<FormattedHTMLMessage id="TRANSLATION_WITH_CSS"/>` which will also produce message with HTML inside `span` tag.
Example translation key could look like following:
```shell
TRANSLATION_WITH_CSS = This is my <strong>text</strong>
```

### Switching between languages

Use `LanguageContext.Consumer` to switch languages.

```jsx
 <LanguageContext.Consumer>
  {context => (<div className="App">
    <button onClick={() => context.changeLanguage("en")}>English</button>
    <button onClick={() => context.changeLanguage("es")}>Spanish</button>
  </div>)}
</LanguageContext.Consumer>
```

> Full application code is available on GitHub. Visit [simplelocalize/simplelocalize-react-intl repository](https://github.com/simplelocalize/simplelocalize-react-intl).

## Edit your translations

Now you can edit messages in the translation editor and publish them using 'Save & Publish'. Your users will automatically see the changes!

![formatjs translation management](/docs/change-translations.gif)

Resources:

- [Guide: FormatJS CLI integration](/docs/integrations/format-js) - extract translation keys with FormatJS CLI
- [Guide: SimpleLocalize CLI integration](/docs/cli/i18n-keys-extraction/) - extract translation keys with SimpleLocalize CLI
- [Blog post: FormatJS and React application localization](/blog/posts/formatjs-reactjs-internationalization/) - read blog post about FormatJS and React localization
- [Docs: FormatJS](https://formatjs.io/docs/getting-started/installation) - FormatJS documentation page


FormatJS


![format js cli importing](/docs/format-js-cli.jpg)

## Overview

FormatJS (formerly known also as react-intl) provide JavaScript CLI tool for extracting i18n keys. You can extract all information from `<FormattedMessage/>` tags and save it into JSON file by using FormatJS CLI.
```tsx
<FormattedMessage 
    id="YOUR_TRANSLATION_KEY" 
    defaultMessage="Your default translation text" 
    description="Your code comment for translators"/>
```
Then, you can use SimpleLocalize CLI to upload exported JSON file. It will automatically create
missing translation keys from `id`, add `defaultMessage` as a default translation, and save `description` in the translation editor.

Remember to also check links below this guide to learn how to integrate realtime translation updates in your web application.

## Installation

Install Format JS CLI

```bash
# Using NPM
npm i -D @formatjs/cli

# Using yarn
yarn add -D @formatjs/cli
```

Install SimpleLocalize CLI

```shell
curl -s https://get.simplelocalize.io/install | bash
```

Problems with CLI? See [troubleshooting section](/docs/cli/troubleshooting).

## Configuration

Add the following command to your `package.json` scripts:

```json
{
  "scripts": {
    "extract": "formatjs extract 'src/**/*.{ts,js,tsx,jsx}' --out-file lang.json",
    "upload-i18n": "simplelocalize upload --apiKey <PROJECT_API_KEY> --uploadPath ./lang.json --uploadFormat simplelocalize-json --languageKey en",
    "download-i18n": "simplelocalize download --apiKey <PROJECT_API_KEY> --downloadPath ./messages.json --downloadFormat multi-language-json"
  }
}
```

## Usage

Use extract script to start FormatJS CLI extraction. It will save all translation keys in `lang.json` file.

```shell
$ npm run extract
```

Run `upload-i18n` script to upload found translation keys

```shell
$ npm run upload-i18n
```

## Translate messages in the editor

Your translation keys will show up in the translation editor.

![translation editor](/docs/translation-editor.png)


## Use translations

Now, you have options to get your translations.

### Live updates

Fetch your translations from SimpleLocalize CDN using your favourite HTTP client.

![translation cdn](/docs/translations-hosting-schema.jpg)

Learn how to [configure live translation updates with FormatJS](/docs/integrations/format-js/)

### Download translation files

Download JSON file with translation to your project files with CLI. Run `download-i18n` script to download ready to use JSON file with all translations.

```shell
$ npm run download-i18n
```



### Resources:

- [Guide: FormatJS real-time translation updates](/docs/integrations/format-js)
- [Blog post: FormatJS and React application localization](/blog/posts/formatjs-reactjs-internationalization/)
- [FormatJS CLI message extraction](https://formatjs.io/docs/getting-started/message-extraction)


FormatJS CLI


List of all supported file formats. You can use this values to upload or download translations in a selected format. 

Format value | Description
----- | ---
[multi-language-json](/docs/file-formats/multi-language-json) | JSON file with all translations
[single-language-json](/docs/file-formats/single-language-json) | JSON file with one language (use `languageKey` param to specify language)
[simplelocalize-json](/docs/file-formats/simplelocalize-json) |  JSON format prepared for integration purposes
[excel](/docs/file-formats/excel) | Microsoft Excel spreadsheet in *.xlsx format
[csv](/docs/file-formats/csv) | `,` or `;` separated translation keys
[yaml](/docs/file-formats/yaml) | yaml file format
[android](/docs/file-formats/android-xml) | XML Resource Strings file
[localizable-strings](/docs/file-formats/localizable-strings) | Localizable.strings file format
[java-properties](/docs/file-formats/java-properties) | Java properties file
[po-pot](/docs/file-formats/gettext-po-pot) | PO/POT files
[php-array](/docs/file-formats/php-array) | PHP Array file 
[module-exports](/docs/file-formats/module-exports) | `module.exports` file 


## Example usage

### CLI
Download translation file in `multi-language-json` format.
```properties
simplelocalize download \ 
  --apiKey <PROJECT_API_KEY> \ 
  --downloadFormat multi-language-json
```


### Rest API

Import translations in `java-properties` format.

```shell
curl
    --request POST \
    --url 'https://api.simplelocalize.io/api/v2/import?uploadFormat=java-properties' \
    --header 'x-simplelocalize-token: <API_KEY>' \
    --form file=@/path/to/your/file.properties
```


File formats


![Export translation flow](/docs/export-translations.jpg)

Export translations from SimpleLocalize translation editor into any format including Excel and JSON format. The export feature allows you to save translations locally or send them to translators without giving access to the translation editor.
The user can choose to export the content in a wide variety of formats including:
- [Excel spreadsheet](/docs/file-formats/excel), 
- [JSON (one file)](/docs/file-formats/multi-language-json), 
- [JSON (one file per language)](/docs/file-formats/single-language-json), 
- [Yaml](/docs/file-formats/yaml), 
- [Java Properties](/docs/file-formats/java-properties), 
- [Localizable Strings](/docs/file-formats/localizable-strings), 
- [Resource XML](/docs/file-formats/android-xml), 
- [PHP Array](/docs/file-formats/php-array), 
- [PO/POT File](/docs/file-formats/gettext-po-pot), 
- [Module Exports](/docs/file-formats/module-exports).


![Export translations section](/docs/export-section.png)

In order to export translations, open your project and switch tab to '**Data**'. Now, select a format by clicking the icon and start export by 
clicking '**Start export**' button. Export shouldn't take more than 10 seconds. 
After that, you will be able to download translations by clicking '**Click to download the file**'.



Resources:
- Learn how to [export translations using CLI](/docs/cli/download-translations)
- Learn how to [export translations using API](/docs/api/export-translations)
- Learn how to [import translations using Web](/docs/general/import)
- Learn how to [import translations using API](/docs/api/import-translations)
- Learn how to [import translations using CLI](/docs/cli/upload-translations)


Export translations


![Import translation flow](/docs/import-translations.jpg)

Import your translations using Excel, JSON or CSV format. The import feature allows you to add your existing data to the translation editor.
This feature can be also used to modify existing translations.

In order to import translations, please go to the '**Data**' tab and scroll down to '**Import translations**' section.

![import translation from Excel file](/docs/import-translations-from-a-file.png)

All imports are performed in the background and in some cases it may take a while to import a file. Usually, the process should take longer than 1/2 minutes. You can track import process in the '**Activity**' tab.

### Available import formats
- [Excel spreadsheet](/docs/file-formats/excel), 
- [JSON (one file)](/docs/file-formats/multi-language-json), 
- [JSON (one file per language)](/docs/file-formats/single-language-json), 
- [SimpleLocalize JSON](/docs/file-formats/simplelocalize-json), 
- [Yaml](/docs/file-formats/yaml), 
- [Java Properties](/docs/file-formats/java-properties), 
- [Localizable Strings](/docs/file-formats/localizable-strings), 
- [Resource XML](/docs/file-formats/android-xml), 
- [PHP Array](/docs/file-formats/php-array), 
- [PO/POT File](/docs/file-formats/gettext-po-pot), 
- [Module Exports](/docs/file-formats/module-exports).

Resources:
- Learn how to [import translations using API](/docs/api/import-translations)
- Learn how to [import translations using CLI](/docs/cli/upload-translations)
- Learn how to [export translations using CLI](/docs/cli/download-translations)
- Learn how to [export translations using API](/docs/api/export-translations)
- Learn how to [export translations using Web](/docs/general/export-translations)



Import translations


Image you have a customer who would like to use a different translation for some translation keys and languages. You don't
want to change this translation for everyone. This should apply only for one or a few clients.

![how to handle customer-specific and industry-specific translations](/docs/customer-specific-translations.jpg)

With SimpleLocalize you can handle such situations with ease! 

## Create customer context

Open 'Languages' tab and click 'Add customer context' button. Enter 'customer id' which should be unique for your project. 
You can also add some description to recognize this customer later.

![add customer-specific context](/docs/add-context.gif)

Customer ID can have max length of 40 characters and contain only letters, numbers, dashes ('-'),
and underscores ('_').

## Add customer-specific translations

Now you can add customer-specific translation in the translation editor just like
any other language translation! Save changes and [publish translations](/docs/general/translation-hosting).

![add customer-specific translation](/docs/add-customer-specific-translation.gif)

## Access customer-specific translations

You can access your customer-specific translations using CDN links like below:

```bash
# Fetch all translations with translations for given customerId
https://cdn.simplelocalize.io/{{projectToken}}/_latest/_index_{{customerId}}

# Fetch translations for given language key with translations for given customerId
https://cdn.simplelocalize.io/{{projectToken}}/_latest/{{languageKey}}_{{customerId}}
```


### Example

```bash
# Fetch project translations for all languages for given `my_customer`
https://cdn.simplelocalize.io/MY-PROJECT-TOKEN/_latest/_index_my_customer
{
  "de" : {
    "HELLO_WORLD" : "Hallo" //default translation for 'de'
  },
  "en" : {
    "HELLO_WORLD" : "Hello My Customer!" //customized translation for 'en' and 'my_customer'
  }
}
```

If there is no translation for given `{{customerId}}`, then the CDN will return a default translation for translation key.
If you try to access translations for `{{customerId}}` who does not exist in SimpleLocalize, then CDN will return response with 404 HTTP code.


## Access customers with customized translations 

You can check first if there are any translations for given `{{customerId}}`. To do that you can fetch a list with all 
customers and check if your customer is on it. If yes, then you have 100% confidence that CDN request will return translations.

### Example

```bash
# Fetch all customers for given project
https://cdn.simplelocalize.io/MY-PROJECT-TOKEN/_latest/_customers
[
  {
    "id": "my_customer_id" 
  },
  {
    "id": "874259234_my_customer"
  }
]
```

`id` from the response is equal to `{{customerId}}` in this article, and this is the value which you set up in the 'Customer-specific translations' section in the 'Language' tab.

![customer-specific translation id](/docs/customer-specific-translations-id.png)



Customer translations


## Contact

- E-mail: [contact@simplelocalize.io](mailto:contact@simplelocalize.io)

## Service Outages

- [Service status](https://stats.uptimerobot.com/4QGZxhJYKp)
- [@simplelocalize](https://twitter.com/simplelocalize) 


## Live Chat Support

In urgent situations do not hesitate to contact me directly:

- [@simplelocalize](https://twitter.com/simplelocalize)
- [@jakub_pomykala](https://twitter.com/jakub_pomykala)

If you want just have a chat with me, then you are also welcomed. ☺️

## Wishlist & Feedback

If you need something special, or you think that some feature or integration would make your life much easier with i18n, then tell me about it using contact channels above. 
Let me handle the things related with i18n, so you or your team won't need to take care about it. ☺️

Sincerely, [Jakub Pomykała 🌱](https://jpomykala.com)


Support


## Quick Start

Learn how upload and download translations from your code on GitHub. This guide will show you how to configure [GitHub Actions](https://github.com/features/actions) pipeline
import translations from repository file and download translated version to your project files.

## Download translations action

Download translations file from SimpleLocalize i18n Editor to temporary action files. 

> Remember: Run this action **before** building application step.

```yml
name: 'Download translations'
on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Download translations
        uses: simplelocalize/download@latest
        with:
          apiKey: <YOUR_API_KEY>
          downloadPath: ./output-sample.json
          downloadFormat: multi-language-json
```

## Upload translations action

Upload translations file from repository to SimpleLocalize using SimpleLocalize Upload Action.

```yml
name: 'Upload translations'
on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Upload translations
        uses: simplelocalize/upload@latest
        with:
          apiKey: <YOUR_API_KEY>
          uploadPath: ./input-sample.json
          uploadFormat: multi-language-json
```


## Resources
- [All supported translation file formats](/docs/general/file-formats/)
- [Sample project with GitHub Actions](https://github.com/simplelocalize/sample-github-action-project)


GitHub Actions


Extract translation keys from your project files. Choose 'projectType' and invoke 'extract' command. The CLI will upload found translation keys to the translation editor.
The CLI will process your local files for given path ('searchDir' parameter) and find all used translation keys.
Every found translation key will be added to the [translation editor](/translation-editor).

![extract translations](/docs/extract-translations.png)

## 💿 Installation

Install SimpleLocalize CLI

```shell
curl -s https://get.simplelocalize.io/install | bash
```

Problems with CLI? See [troubleshooting section](/docs/cli/troubleshooting).

## 👨‍💻 Usage

```properties
simplelocalize extract \
  --apiKey PROJECT_API_KEY \
  --projectType yahoo/react-intl \
  --searchDir ./src
```

## 📖 Supported libraries

Libraries from which you can extract translation keys

| Library | `projectType` value | Ready? | 
| ------------- |-------------:|:----:|
| [react-intl](https://github.com/yahoo/react-intl)      | yahoo/react-intl | ✅
| Standard Android internationalization | google/android      |    ✅ |
| Standard iOS internationalization | apple/ios-macos      |    ✅ |
| [react-i18next](https://github.com/i18next/react-i18next) | i18next/i18next      |    ✅ |
| [mde/ejs](https://github.com/mde/ejs) | mde/ejs | ✅ |
| [ember-intl](https://github.com/ember-intl/ember-intl) | ember-intl/ember-intl      |    [ ] |
| [jekyll-multiple-languages-plugin](https://github.com/Anthony-Gaudino/jekyll-multiple-languages-plugin)      | Anthony-Gaudino/jekyll-multiple-languages-plugin      |   [ ] |
| [dust-intl](https://github.com/yahoo/dust-intl) | yahoo/dust-intl      |    [ ] |
| [handlebars-intl](https://github.com/yahoo/handlebars-intl) | yahoo/handlebars-intl      |    [ ] |

> Do you already **have extracted translation keys to file?** Great! Use Localization CLI Tool to [upload translations to the translation editor](/docs/cli/upload-translations).



## 👩‍🏫 How message extraction works?

For example to translate frontend application in [ReactJS](https://github.com/facebook/react) you can use 3rd party
library like [yahoo/react-intl](https://github.com/yahoo/react-intl):

Example [yahoo/react-intl](https://github.com/yahoo/react-intl) usage in React app code:

```jsx
<FormattedMessage id="LOGIN"/>
```

Translation key `LOGIN` will be found by localization CLI tool.

```shell
simplelocalize extract --apiKey API_KEY --projectType PROJECT_TYPE --searchDir ./src
```

![CLI extraction](/docs/cli-extraction.gif)


🎉 Done! CLI will find i18n keys, and push them to [translation editor](/translation-editor).


Extract keys


Upload existing translations or translation keys from your local project files. 
The uploaded translations and translations keys you can find in the [translation editor](/translation-editor).

![upload translations](/docs/upload-translations.png)

## 💿 Installation

Install SimpleLocalize CLI

```shell
curl -s https://get.simplelocalize.io/install | bash
```

Problems with CLI? See [troubleshooting section](/docs/cli/troubleshooting).

## 👨‍💻 Usage

### Upload all language translations from one file

```properties
simplelocalize upload \
 --apiKey PROJECT_API_KEY \
 --uploadPath ./all-translations.json \
 --uploadFormat multi-language-json
```

Learn more about [multi-language-json](/docs/file-formats/multi-language-json).


### Upload one language translations from one file

```properties
simplelocalize upload \
 --apiKey PROJECT_API_KEY \
 --uploadPath ./english-translations.json \
 --uploadFormat single-language-json \
 --languageKey en
```

Learn more about [single-language-json](/docs/file-formats/single-language-json).


### Upload all language translations from multiple files

```properties
simplelocalize upload \
 --apiKey PROJECT_API_KEY \
 --uploadPath ./my-{lang}-translations.json \
 --uploadFormat single-language-json
```

In this case SimpleLocalize CLI will discover all files which will match to `my-???-translations.json` in directory and use `???` as a language key.
It's useful when you have many files with translations. Thanks to that, you can upload all file at once.


## 📦 Available `--uploadFormat` values

uploadFormat | Description
--- | ---
[multi-language-json](/docs/file-formats/multi-language-json) | JSON file with all translations
[single-language-json](/docs/file-formats/single-language-json) | JSON file with one language (use `languageKey` param to specify language)
[simplelocalize-json](/docs/file-formats/simplelocalize-json) |  JSON format prepared for integration purposes
[excel](/docs/file-formats/excel) | Microsoft Excel spreadsheet in *.xlsx format
[csv](/docs/file-formats/csv) | `,` or `;` separated translation keys
[yaml](/docs/file-formats/yaml) | yaml file format
[android](/docs/file-formats/android-xml) | XML Resource Strings file
[localizable-strings](/docs/file-formats/localizable-strings) | Localizable.strings file format
[java-properties](/docs/file-formats/java-properties) | Java properties file
[po-pot](/docs/file-formats/gettext-po-pot) | PO/POT files
[php-array](/docs/file-formats/php-array) | PHP Array file
[module-exports](/docs/file-formats/module-exports) | `module.exports` file

### Example

![CLI upload](/docs/cli-upload.gif)


> SimpleLocalize CLI can also upload JSON generated by [FormatJS CLI](https://formatjs.io/docs/tooling/cli/). Learn more about [FormatJS CLI + SimpleLocalize CLI integration](/docs/integrations/format-js-cli)



## 🗂 Translations are in multiple files

If your project structure uses one translation file per language translations then you can use special syntax
in `uploadPath` option. Use `{lang}` variable to load all translations from JSON files.

### Example

Let's assume you have project structure like below
![project structure](/docs/project-structure.png)

In that case `uploadPath` param should look like following `messages_{lang}.properties`. CLI will automatically extract
language key from file name and upload it accordingly.

### Example command usage

```properties
simplelocalize upload \
 --apiKey PROJECT_API_KEY \ 
 --uploadPath ./messages_{lang}.properties \ 
 --uploadFormat java-properties
```


> Learn how to [download translations](/docs/cli/download-translations). Optionally, you can also check how to [export translations using API](/docs/api/export-translations). 


Upload translations


Download translations to your local files using CLI. Choose the best matching file format for your project. Invoke 'download' command to get the latest version of translations.


![download translations](/docs/download-translations.png)

## 💿 Installation

Install SimpleLocalize CLI

```shell
curl -s https://get.simplelocalize.io/install | bash
```

Problems with CLI? See [troubleshooting section](/docs/cli/troubleshooting).

## 👨‍💻 Usage

### Download all language translations into one file

```properties
simplelocalize download \
  --apiKey <PROJECT_API_KEY> \
  --downloadFormat multi-language-json \
  --downloadPath ./all-translations.json
```

Learn more about [multi-language-json](/docs/file-formats/multi-language-json).

### Download one language translations into one file

```properties
simplelocalize download \
  --apiKey <PROJECT_API_KEY> \
  --downloadFormat multi-language-json \
  --downloadPath ./english-translations.json \
  --languageKey en
```

Learn more about [single-language-json](/docs/file-formats/single-language-json).

### Download all language translations into multiple files

```properties
simplelocalize download \
 --apiKey PROJECT_API_KEY \
 --downloadPath ./my-{lang}-translations.json \
 --downloadFormat single-language-json
```

In this case SimpleLocalize CLI will take all your project language keys and fetch translations for each of them.
After that each translation file will be saved in a directory specified in `--uploadPath` with specified format: `my-{languageKey}-translations.json`  
Thanks to that, you can download all files at once.


## 📦 Available `--downloadFormat` values

downloadFormat | Description
--- | ---
[multi-language-json](/docs/file-formats/multi-language-json) | JSON file with all translations
[single-language-json](/docs/file-formats/single-language-json) | JSON file with one language (use `languageKey` param to specify language)
[excel](/docs/file-formats/excel) | Microsoft Excel spreadsheet in *.xlsx format
[yaml](/docs/file-formats/yaml) | yaml file format
[android](/docs/file-formats/android-xml) | XML Resource Strings file
[localizable-strings](/docs/file-formats/localizable-strings) | Localizable.strings file format
[java-properties](/docs/file-formats/java-properties) | Java properties file
[po-pot](/docs/file-formats/gettext-po-pot) | PO/POT files
[php-array](/docs/file-formats/php-array) | PHP Array file
[module-exports](/docs/file-formats/module-exports) | `module.exports` file

### Example

![CLI download](/docs/cli-download.gif)

## 🖊 How to change file names

If you selected format which provides more than one file, then the file name will contain language key which is set in
SimpleLocalize Web (Languages tab). Change the language key and download translations again using CLI to get translation
file with changed name.

### Example command usage
```properties
simplelocalize download \
 --apiKey PROJECT_API_KEY \ 
 --downloadPath ./translations_{lang}.json \ 
 --downloadFormat single-language-json
```

> Learn how to [upload translations using CLI](/docs/cli/upload-translations). Optionally, you can also check how to [import
> translations using API](/docs/api/import-translations). 


Download translations


Learn more what other options you can set up in SimpleLocalize CLI.

## Use configuration file

Create `simplelocalize.yaml` file

```yaml
apiKey: <PROJECT_API_KEY>
projectType: yahoo/react-intl
searchDir: ./src
```

Now you can just run CLI command without passing parameters. Try `simplelocalize extract`.
 to see how it works.

## Custom configuration file path
To use custom configuration file you can use `-c <PATH>` or `--config <PATH>` parameter.

Example

```properties
simpleloclize-cli  --config ./path/to/config.yaml [COMMAND]
```

Please notice that configuration parameter comes before COMMAND!

## Ignore translation keys

```yaml
apiKey: <API_KEY>
projectType: <PROJECT_TYPE>
ignoreKeys:
    - "HEY"
    - "PLEASE"
    - "DO NOT IGNORE ME"
    - ":("
```

Note: Ignore keys feature is only available though configuration file.

## Custom search directory
If you would like to search translation keys in some specific path you can achieve this by adding `searchDir` property, and the path where CLI should search for the keys.

```yaml
apiKey: <API_KEY>
projectType: <YOUR_PROJECT_TYPE>
searchDir: /Users/jpomykala/Workspace/MyProject
```
**Please pay attention to what you are putting in the 'searchDir' property.** Script will go through all files from given path to find the keys - giving a root path may cause high CPU and disc usage.

## Configuration profiles
If you would like to use `simplelocalize.yml` from custom location or with custom name like simplelocalize-dev.yml file, you can achieve that easily by passing path as the first argument.

```bash
$ simplelocalize --config /tmp/simplelocalize-dev.yml [command] --apiKey YOUR_API_KEY
```


More options


Include the CLI into your continuous integration and continuous deployment pipeline. Upload and download translations on every Git push.

## 🤖 Workflow automation

SimpleLocalize can be integrated with any CI/CD service, simply put bash script somewhere in your scripting environment to find and push translation keys:

```shell
$ curl -s https://get.simplelocalize.io/install | bash
$ simplelocalize [command] --apiKey YOUR_API_KEY
```
The best place to run SimpleLocalize script is **after successful build** because this will not result with wrong internationalisation keys caused by invalid syntax.


## Github Actions

Example `build.js` workflow file:

```yaml
name: Deploy

on:
  push:
    branches:
      - master

jobs:
  deploy:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [10.x]
    steps:
      - uses: actions/checkout@v2
      - name: Use Node.js
        uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm install
      - run: npm build
        env:
          CI: ""
      - name: SimpleLocalize
        run: curl -s https://get.simplelocalize.io/install | bash && simplelocalize [command]
```

## AWS CodeBuild

Example `buildspec.yml`

```yaml
version: 0.1
phases:
  pre_build:
    commands:
      - yarn install
  build:
    commands:
      - yarn run test
      - yarn run build
      # Run SimpleLocalize
      - curl -s https://get.simplelocalize.io/install | bash && simplelocalize [command]
```

> Would you like to help us and share your CI/CD configuration? Write us: [contact@simplelocalize.io](mailto:contact@simplelocalize.io)


CI/CD integration


Do you have a problem with running CLI? See solutions for the most frequent SimpleLocalize CLI issues.

> Do you have a problem which is not described here? Let us know: [contact@simplelocalize.io](mailto:contact@simplelocalize.io)

## simplelocalize-cli: No such file or directory

Try to use a special version of CLI:
```bash
$ curl -s https://get.simplelocalize.io/download-and-run | bash
```

It downloads the unzipped CLI version and runs it without creating fancy directory structure.


## Any other problem

In most cases you should use our regular script which is constantly optimized for everyone, like the one below:
```bash
$ curl -s https://get.simplelocalize.io | bash
```
If something is not working properly please [create an issue](https://github.com/simplelocalize/simplelocalize-cli/issues/new) and provide script output. In the meantime, you can use one of 2 other options to run CLI.


### Option 1: I have Java 11+ installed on my system, let me just use app in *.jar file.
```bash
$ curl -s https://get.simplelocalize.io/run-jar | bash
```

### Option 2: I want to use *.jar file, but I don't have JDK installed.
```bash
$ curl -s https://get.simplelocalize.io/install-jdk-run-jar | bash
```


Troubleshooting


SimpleLocalize API gives you an ability to create your own integrations. 
API provides endpoint to [create](/docs/api/add-translations), [update](/docs/api/update-translations), [read](/docs/api/read-translations), and [delete](/docs/api/delete-translations) translations.
Optionally, you can [import translations](/docs/api/import-translations) and [export translations](/docs/api/export-translations). 

![get started with localization api](/docs/get-started-api.png)

## API and CDN Authorization

'API Key' and 'Project token' can be found in the 'Integration' tab in your
project. Please see the screen below.

![simplelocalize project credentials](/docs/simplelocalize-api-key.png)

### API Key

Each request which adds or updates the translation data needs to be authorized. 
Every request sent to such endpoint needs to have `X-SimpleLocalize-Token` header with `API Key` value. 

> You should never expose this key to the public.

### Project token

Project token can be exposed and used in client-side applications,
it allows you to fetch translations from the CDN on client side.





### Description
This endpoint allows you to:

- create new translation keys and translations
- add new languages/locales
- modify existing translations (`importOptions=REPLACE_TRANSLATION_IF_FOUND`)

Check `importOptions` section to learn more. If you use this endpoint, note that it requires [authorization](/docs/api/get-started).

### Endpoint behaviour
- Endpoint will add translation for translation key and language if not found.
- Endpoint won't replace existing translations by default. Use [update translations endpoint](/docs/api/update-translations/) or `importOption=REPLACE_TRANSLATION_IF_FOUND`.
- Endpoint will automatically add language if not found.
- Endpoint won't create customerId automatically if not found. 
- Endpoint will automatically update last seen value in translation editor.
- Endpoint won't update a translation, if `key` and/or `language` is missing.


## <span class="badge badge-success">POST</span> Endpoint

```http request
https://api.simplelocalize.io/api/v1/translations
```

## Example cURL

```shell
curl 
    --location 
    --request POST 'https://api.simplelocalize.io/api/v1/translations' \
    --header 'X-SimpleLocalize-Token: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "content": [
            {
                "key": "EXAMPLE_KEY",
                "language": "en",
                "text": "example text"
            },
            {
                 "key": "SALE",
                 "language": "pl",
                 "text": "Sprzedaż",
                 "customerId": "my_customer"
            }
        ]
    }'
```

### Request fields

- `key` (required) - unique translation key for a project
- `language` - project language key
- `text` - translated message for given `key`, `language` and `customerId` (optional)
- `customerId` - if `customerId` is provided, then translation will be assigned to the customer translation for given `key` and `language`. Otherwise, translation will be treated as a default translation for given `key` and `language`. [See customer-specific translation](/docs/general/customer-specific-translations/)

### Import options

Use query param `importOptions` to invoke custom logic after or during the import. You can pass more than one import
option.

| Option value | Description |
| :-------- | --- |
| `REPLACE_TRANSLATION_IF_FOUND` | Replaces translation for key if the key already exists. Without this option SimpleLocalize will only add new translations. | 
| `PUBLISH_AFTER_IMPORT` | Translations will be published automatically to the CDN after successful import. **Option available only in paid plans.** Check also how to [publish translations using API endpoint](/docs/api/publish-translations) |
| `FAIL_FAST` (soon) | Request will fail on first encountered warning, processed translations **won't be reverted** to the original state |
| `REVERT_ON_FAIL` (soon) | Request will fail on first encountered warning, and processed translations **will be reverted** to the original state before the request |


## Example response
```json
{
  "msg": "OK",
  "status": 200,
  "data": {
    "uniqueKeysProcessed": 2,
    "processedWithWarnings": false,
    "message": "OK"
  }
}
```

### Response fields
- `uniqueKeysProcessed` - informs about number of processed translation keys which was sent by a client,
- `processedWithWarnings` - informs about encountered warnings during import,
- `message` - informs about warning details.


Add translations


This is split into two sections, public CDN and private API. CDN offers free, fast and public access to your translations. 
Second section describes private access which [requires authorization](/docs/api/get-started) and cannot be posted publicly.

## Fetching from CDN

Fetching from CDN is available for everyone. It's fast and safe to share link to the public. Remember to use a **project token** to access CDN resources.

### Where to find a project token

![simplelocalize project token location](/docs/where-project-token-is-located.png)

### <span class="badge badge-primary">GET</span> Get all translations

```http request
https://cdn.simplelocalize.io/:projectToken/_latest/_index
```
Example response
```json
{
  "de": {
    "SALE": "Verkauf",
    "ADDRESS": "Adresse"
  },
  "fr": {
    "SALE": "soldes",
    "ADDRESS": "adresse"
  }
}
```


### <span class="badge badge-primary">GET</span> Get translations by language key
```http request
https://cdn.simplelocalize.io/:projectToken/_latest/:languageKey
```
Example response
```json
{
  "SALE": "Verkauf",
  "ADDRESS": "Adresse"
}
```

### <span class="badge badge-primary">GET</span> Get languages
```http request
https://cdn.simplelocalize.io/:projectToken/_latest/_languages
```
Example response
```json
[
   {
      "key": "de",
      "name": "Deutsch"
   },
   {
      "key": "en",
      "name": "English"
   },
   {
      "key": "es",
      "name": "Español"
   }
]

```

## Fetching from API 

If you are using this endpoint, the [authorization](/docs/api/get-started) is required. 
Add API Token for your project as a `X-SimpleLocalize-Token` request header.

### <span class="badge badge-primary">GET</span> Query all translations
```http request
https://api.simplelocalize.io/api/v1/translations
```

Available query parameters

Query parameter | Description
--- | ---
`text` | query for translated text, uses 'contains with ignore case'
`key` | filter by given translation key, uses 'equals'
`language` | filter by given language key, uses 'equals'
`customerId` | filter by given customer id, uses 'equals'; [see customer-specific translations](/docs/general/customer-specific-translations/)


### <span class="badge badge-primary">GET</span> Query translations with language 'de' and translation key 'hello'
```http request
https://api.simplelocalize.io/api/v1/translations?languageKey=de&key=hello
```

### Example response 

```json
{
    "msg": "OK",
    "status": 200,
    "data": {
        "content": [
            {
                "key": "CREATE.TAGS",
                "language": "en",
                "text": "Tags"
            },
            //...
        ]
    }
}
```



Read translations


This endpoint allows you to operate only on existing translations. 
Use this endpoint to update translation for given translation key and language or translation key, language and customer id. 
Using this endpoint requires [authorization](/docs/api/get-started).

## <span class="badge badge-info">PATCH</span> Endpoint

```http request
https://api.simplelocalize.io/api/v1/translations
```

## Example cURL
```shell
curl 
    --location 
    --request PATCH 'https://api.simplelocalize.io/api/v1/translations' \
    --header 'X-SimpleLocalize-Token: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "content": [
            {
                "key": "EXAMPLE_TRANSLATION_KEY",
                "language": "en",
                "text": "example text"
            },
            {
                "key": "EXAMPLE_TRANSLATION_KEY",
                "language": "en",
                "text": "customer example text",
                "customerId": "my_customer"
            }
        ]
    }'
```

### Request fields

- `key` (required) - unique translation key for a project
- `language` (required) - project language key
- `text` - translated message for given `key`, `language` and `customerId` (optional)
- `customerId` - if `customerId` is provided, then translation will be assigned to the customer translation for given `key` and `language`. Otherwise, translation will be treated as a default translation for given `key` and `language`. [See customer-specific translation](/docs/general/customer-specific-translations/)

## Example successful response
```json
{
  "msg": "OK",
  "status": 200,
  "data": {
    "numberOfUpdates": 2,
    "numberOfFailures": 4,
    "numberOfInserts": 1,
    "failures": [
      "Cannot update translation. Translation key value is empty.",
      "Cannot update translation. Language value is empty for key 'MY_TRANSLATION_KEY'.",
      "Cannot update translation. Language 'wrong-lang-key' does not exist in the project.",
      "Cannot update translation. Translation key 'MY_TRANSLATION_KEY' does not exist in the project."
    ]
  }
}
```

### Response fields
- `numberOfUpdates` - informs about number of processed translation updates,
- `numberOfFailures` - informs about number of processed translation update failures,
- `numberOfInserts` - informs about number of newly added translations,
- `failures` - informs about failed updates.


### Available update options

Use query param 'updateOptions' to do invoke custom logic after or during the import. You can pass more than one update
option.

updateOptions | Description
--- | ---
`CREATE_KEY_IF_NOT_FOUND` | Creates translation key which are not present in the project.


> Check how to [publish translations using API](/docs/api/publish-translations)


Update translations


This endpoint allows you deleting translation keys. The usage of this endpoint requires [authorization](/docs/api/get-started). 

> Endpoint is available only in [paid plans](/pricing).

## <span class="badge badge-danger">DELETE</span> Endpoint

```http request
https://api.simplelocalize.io/api/v1/translations
```

## Example cURL

```shell
curl 
    --location 
    --request DELETE 'https://api.simplelocalize.io/api/v1/translations' \
    --header 'X-SimpleLocalize-Token: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "content": [
            {
                "key": "EXAMPLE_KEY"
            }
        ]
    }'
```

### Request fields

- `key` - unique translation key for a project

## Example response
```json
{
  "msg": "OK",
  "status": 200,
  "data": {
    "deletedTranslations": 2
  }
}
```

### Response fields

- `deletedTranslations` - informs about deleted **translation keys**


Delete translation keys


This endpoint allows you to publish currently saved translations in translation editor. 
If you use this endpoint, note that it requires [authorization](/docs/api/get-started).

> Endpoint is available only in [paid plans](/pricing). 

## <span class="badge badge-success">POST</span> Endpoint

```
https://api.simplelocalize.io/api/v1/translations/publish
```

## Example cURL

```shell
curl 
    --location 
    --request POST 'https://api.simplelocalize.io/api/v1/translations/publish' \
    --header 'X-SimpleLocalize-Token: <API_KEY>'
```

Request to this endpoint may require more time to complete for projects with many translations.

## Example successful response
```json
{
  "msg": "OK",
  "status": 200,
  "data": {
    "message": "OK"
  }
}
```


Publish translations


Import translations from a file. Check 'Import options' section to
learn more about possibilities. Using this endpoint requires [authorization](/docs/api/get-started).

## <span class="badge badge-success">POST</span> Endpoint

```
https://api.simplelocalize.io/api/v2/import?uploadFormat=
```

## Example cURL

### Import all translations from one file

```shell
curl
  --request POST \
  --url 'https://api.simplelocalize.io/api/v2/import?uploadFormat=multi-language-json' \
  --header 'x-simplelocalize-token: <API_KEY>' \
  --form file=@/path/to/your/all-translations.json
```

Learn more about [multi-language-json](/docs/file-formats/multi-language-json).

### Import translations for one language

```shell
curl
  --request POST \
  --url 'https://api.simplelocalize.io/api/v2/import?uploadFormat=single-language-json&languageKey=en' \
  --header 'x-simplelocalize-token: <API_KEY>' \
  --form file=@/path/to/your/english-translations.json
```

Learn more about [single-language-json](/docs/file-formats/single-language-json).

### Query parameters

Parameter | Description
--- | ---
`uploadFormat` | Set upload format to tell API how we should read the file with translations
`languageKey` | Set language key if you want import translations for only one language
`importOptions` | Set import options to do invoke custom logic after or during the import


### Available `uploadFormat` values

uploadFormat | Description
--- | ---
[multi-language-json](/docs/file-formats/multi-language-json) | JSON file with all translations
[single-language-json](/docs/file-formats/single-language-json) | JSON file with one language (use `languageKey` param to specify language)
[simplelocalize-json](/docs/file-formats/simplelocalize-json) |  JSON format prepared for integration purposes
[excel](/docs/file-formats/excel) | Microsoft Excel spreadsheet in *.xlsx format
[csv](/docs/file-formats/csv) | `,` or `;` separated translation keys
[yaml](/docs/file-formats/yaml) | yaml file format
[android](/docs/file-formats/android-xml) | XML Resource Strings file
[localizable-strings](/docs/file-formats/localizable-strings) | Localizable.strings file format
[java-properties](/docs/file-formats/java-properties) | Java properties file
[po-pot](/docs/file-formats/gettext-po-pot) | PO/POT files
[php-array](/docs/file-formats/php-array) | PHP Array file
[module-exports](/docs/file-formats/module-exports) | `module.exports` file

### Available `importOptions` values

Use query param `importOptions` to do invoke custom logic after or during the import. You can pass more than one import
option. If you need more import options let us know: contact@simplelocalize.io

`importOptions` | Description
--- | ---
`REPLACE_TRANSLATION_IF_FOUND` | Replaces translation for key if the key already exists. Without this option SimpleLocalize will only add new translations. 
`PUBLISH_AFTER_IMPORT` | Translations will be published automatically to the CDN after successful import. **Option available only in Developer and Team plan.** Check also how to [publish translations using API endpoint](/docs/api/publish-translations)


### Example response

```json
{
  "numberOfKeysFound": 2137,
  "numberOfUniqueKeysFound": 1004,
  "foundLanguages": [
      {
        "key": "pl",
        "name": "Polish"
      }
  ]
}
```

## Deprecated endpoints

### <span class="badge badge-success">POST</span> Deprecated endpoint (2021-01-24)

```https://api.simplelocalize.io/api/v1/import```

### <span class="badge badge-success">POST</span> Deprecated endpoint (2019-12-10)
```https://api.simplelocalize.io/api/v1/files```



Export translations to downloadable file. Using this endpoint requires [authorization](/docs/api/get-started).

## <span class="badge badge-primary">GET</span> Endpoint

```shell
https://api.simplelocalize.io/api/v3/export
```

## Example cURL

### Download all translations into one file 

```shell
curl
  --request GET \
  --url https://api.simplelocalize.io/api/v3/export?downloadFormat=multi-language-json \
  --header 'x-simplelocalize-token: <API_KEY>'
```

Learn more about [multi-language-json](/docs/file-formats/multi-language-json).

### Download translations for one language

```shell
curl
  --request GET \
  --url https://api.simplelocalize.io/api/v3/export?downloadFormat=single-language-json&languageKey=en \
  --header 'x-simplelocalize-token: <API_KEY>'
```

Learn more about [single-language-json](/docs/file-formats/single-language-json).

### Query parameters

Parameter | Description
--- | ---
`downloadFormat` | (required) Set the download format. See table below.
`languageKey` | (optional) Set the language key if you want to export translations just for one language
`customerId` | (optional) Set the customer id if you want to export translations just customer translations

### Available `downloadFile` values

downloadFormat | Description
--- | ---
[multi-language-json](/docs/file-formats/multi-language-json) | JSON file with all translations
[single-language-json](/docs/file-formats/single-language-json) | JSON file with one language (use `languageKey` param to specify language)
[excel](/docs/file-formats/excel) | Microsoft Excel spreadsheet in *.xlsx format
[yaml](/docs/file-formats/yaml) | yaml file format
[android](/docs/file-formats/android-xml) | XML Resource Strings file
[localizable-strings](/docs/file-formats/localizable-strings) | Localizable.strings file format
[java-properties](/docs/file-formats/java-properties) | Java properties file
[po-pot](/docs/file-formats/gettext-po-pot) | PO/POT files
[php-array](/docs/file-formats/php-array) | PHP Array file
[module-exports](/docs/file-formats/module-exports) | `module.exports` file

## Example response

```json
{
    "msg": "OK",
    "status": 200,
    "data": {
        "url": "https://cdn.simplelocalize.io/29fdc3462/snapshot_2021-10-12_13-01-25_063/translations.json"
    }
}
```

## Deprecated APIs below

### <span class="badge badge-primary">GET</span> Deprecated endpoint

```shell
https://api.simplelocalize.io/api/v2/export
```

### Deprecated export file formats

exportType | Description
--- | ---
FORMAT_JS | format used by FormatJS library
JEKYLL | format used by [Jekyll plugin](https://github.com/kurtsson/jekyll-multiple-languages-plugin)
SPRING | format used by Java and Spring applications (messages_xx.properties)
ANDROID | format used by standard Android library
IOS_MACOS | format used by standard iOS library
EXCEL | Microsoft Excel spreadsheet in *.xlsx format




Learn how to start auto-translation job to translate text in your project to another language using automated translation services
like DeepL or Google Translate. In the second section you will learn how to track progress of started auto-translation jobs.

## <span class="badge badge-success">POST</span> Start auto-translation job

```http request
https://api.simplelocalize.io/api/v1/jobs/auto-translate
```

### Example cURL

```shell
curl 
    --location 
    --request POST 'https://api.simplelocalize.io/api/v1/jobs/auto-translate' \
    --header 'X-SimpleLocalize-Token: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "translationProvider": "DEEPL",
        "options": ["FORCE_REPLACE"],
        "targetProjectLanguage": "en",
        "targetLanguage": "EN-GB",
        "sourceProjectLanguage": "pl",
        "sourceLanguage": "PL",
    }'
```

### Request fields

- `translationProvider` (required) - translation provider (`GOOGLE_TRANSLATE` or `DEEPL`),
- `targetProjectLanguage` (required) - target language key from your project,
- `targetLanguage` (required) - target provider language key,
- `sourceProjectLanguage` - source language key from your project,
- `sourceLanguage` - source language key,
- `options` - auto-translate options array.

### Available `options` field values

Options field must be always provided as string array.

Option Value | Description
--- | ---
`USE_TRANSLATION_KEYS` | Use translation keys as source, if no translation available
`FORCE_REPLACE` | Translate all and replace existing translations
`EXCLUDE_VARIABLES` | Do not translate variables like: `{{count}}`
`AUTO_PUBLISH` | Publish translations to CDN after successful translation (changes are pushed to the "Latest Environment")

### Additional request fields for DeepL provider

- `deeplGlossaryId` - specify the glossary to use. This requires `deeplApiKey` and `sourceLanguage` field to be set and
  the language pair of the glossary has to match the language pair of the request,
- `deeplApiKey` - if you use DeepL glossary, then your DeepL API Key is required. The API Key is used only during
  auto-translation job, and it's removed once job is finished. It won't show up in the job details at any time.

See [DeepL API documentation](https://www.deepl.com/docs-api/translating-text/request/).

### Target Language and Source Language

- `targetLanguage` and `sourceLanguage` are different for each translation provider.
- `targetProjectLanguage` and `sourceProjectLanguage` comes from your project

#### Where to find project language keys?

Values for `targetProjectLanguage` and `sourceProjectLanguage` must be provided as language keys. Language keys can be
found in the Languages tab in your project.

![Where to find project language keys in SimpleLocalize?](/docs/where-to-find-language-key.png)

#### Language keys for Google Translate

Here is a list of example language keys supported by Google Translate as target or source language key.

- `en` for English
- `pl` for Polish
- `pt` for Portuguese
- `sv` for Swedish

[See full list of supported language keys](https://cloud.google.com/translate/docs/languages)

#### Language keys for DeepL
Here is a list of example language keys supported by DeepL as target or source language key.
- `EN-GB` for English (British)
- `PL` for Polish
- `PT-BR` for Portuguese (Brazilian)
- `SV` for Swedish

[See full list of supported language keys](https://www.deepl.com/docs-api/other-functions/listing-supported-languages/)

### Example response
```json
{
  "msg": "OK",
  "status": 200,
  "data": {
    "jobId": "<JOB_ID>",
    "progress": 0.01,
    "state": "STARTED",
    "started": "2021-09-01T11:09:52.919Z",
    "message": "OK",
    "metadata": {},
  }
}
```


## <span class="badge badge-success">GET</span> Get auto-translation jobs

```http request
https://api.simplelocalize.io/api/v1/jobs
```

### Example cURL

```shell
curl 
    --location 
    --request POST 'https://api.simplelocalize.io/api/v1/jobs' \
    --header 'X-SimpleLocalize-Token: <API_KEY>' \
    --header 'Content-Type: application/json'
```

### Example response
```json
{
    "msg": "OK",
    "status": 200,
    "data": [
        {
            "jobId": "42bc498cc33c4ac4866b18f33ce4ed65",
            "progress": 1.0,
            "state": "SUCCESS",
            "message": "Translated 99 texts (chars: 1823)",
            "started": "2021-09-01T11:09:52.919Z",
            "metadata": {
                "targetProjectLanguage": "fr",
                "targetLanguage": "FR",
                "sourceType": "API",
                "options": "FORCE_REPLACE",
                "translationProvider": "DEEPL",
                "sourceProjectLanguage": "en",
                "sourceLanguage": "en"
            }
        },
    ...
    }
```


Auto-translate


The custom build JSON format for different purposes. In most cases you would like to use it to import translation keys and localized messages from different localization programs.
SimpleLocalize will discover automatically what kind of JSON library you use.


### File format example

```json
{
  "translation_key": {
    "message": "my localized message"
  },
  "second_translation_key": {
    "defaultMessage": "my localized message from FormatJS CLI output",
    "description": "Your message to translators. It will also show up in the translation editor"
  }
}
```

You can use `simplelocalize-json` format with [FormatJS CLI](https://formatjs.io/docs/getting-started/message-extraction/). Check [FormatJS CLI integration guide](/docs/integrations/format-js-cli).

## Upload with CLI

```properties
simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat simplelocalize-json \
  --uploadPath ./translations_{lang}.json \
  --languageKey en
```

Learn more about [SimpleLocalize CLI and translations upload](/docs/cli/upload-translations/) feature.

## Download with CLI

### All translations at once

```properties
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat simplelocalize-json \
  --downloadPath ./translations_{lang}.json
```

### One file with one language

```properties
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat simplelocalize-json \
  --downloadPath ./translations_{lang}.json \
  --languageKey en
```

Learn more about [SimpleLocalize CLI and translations download](/docs/cli/download-translations/) feature.

## Import with API

```shell
curl
    --request POST \
    --url 'https://api.simplelocalize.io/api/v2/import?uploadFormat=simplelocalize-json&languageKey=en' \
    --header 'x-simplelocalize-token: <API_KEY>' \
    --form file=@/path/to/your/file.json
```

Learn more about [importing translations with API](/docs/api/import-translations/)

## Export with API

### All translations in one file

```shell
curl
    --request GET \
    --url https://api.simplelocalize.io/api/v3/export?downloadFormat=simplelocalize-json \
    --header 'x-simplelocalize-token: <API_KEY>'
```

### One file with one language

```shell
curl
    --request GET \
    --url https://api.simplelocalize.io/api/v3/export?downloadFormat=simplelocalize-json&languageKey=en \
    --header 'x-simplelocalize-token: <API_KEY>'
```

Learn more about [exporting translations with API](/docs/api/export-translations/)



JSON - SimpleLocalize


The most basic and common JSON format for software app localization. It can be used in any kind of web projects, desktop
program or game. Simple JSON object contains translation key set by a developer during program implementation process,
and localized message for end user.

### File format example

```json
{
  "SALE": "Verkauf",
  "ADDRESS": "Adresse"
}
```

You can also use [multi-language-json format](/docs/file-formats/multi-language-json) to download all translations at
once.

SimpleLocalize also recognizes nested JSON keys like shown below.

```json
{
    "SALE": {
      "NESTED": "Verkauf"
    }
}
```

Above JSON will result with `SALE.NESTED` translation key.


## Upload with CLI

```properties
simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat single-language-json \
  --uploadPath ./translations_{lang}.json
```

Learn more about [SimpleLocalize CLI and translations upload](/docs/cli/upload-translations/) feature.

## Download with CLI

```properties
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat single-language-json \
  --downloadPath ./translations_{lang}.json
```

Learn more about [SimpleLocalize CLI and translations download](/docs/cli/download-translations/) feature.

## Import with API

```shell
curl
    --request POST \
    --url 'https://api.simplelocalize.io/api/v2/import?uploadFormat=single-language-json' \
    --header 'x-simplelocalize-token: <API_KEY>' \
    --form file=@/path/to/your/file.json
```

Learn more about [importing translations with API](/docs/api/import-translations/)

## Export with API

```shell
curl
    --request GET \
    --url https://api.simplelocalize.io/api/v3/export?downloadFormat=single-language-json \
    --header 'x-simplelocalize-token: <API_KEY>'
```

Learn more about [exporting translations with API](/docs/api/export-translations/)



JSON - Single Language


In this section you will learn how to create, query, update and delete customers.
Customers feature is used to change translations for one company or user without altering your base translations. 

## Resources

- What are [customer-specific translations?](/docs/general/customer-specific-translations/)
- [Add translation for customer](/docs/api/add-translations/) by passing customer key in `customerId` field
- [Update customer translations](/docs/api/update-translations/) by passing customer key in `customerId` field
- [Get customer translations from CDN (recommended)](/docs/general/customer-specific-translations/) by passing customer key in URL
- [Get customer translations from API](/docs/api/add-translations/) by passing customer key in `customerId` field

## <span class="badge badge-success">POST</span> Create customer

```http request
https://api.simplelocalize.io/api/v1/customers
```

### Example cURL

```shell
curl 
    --location 
    --request POST 'https://api.simplelocalize.io/api/v1/customers' \
    --header 'X-SimpleLocalize-Token: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "key": "my-customer-2137",
        "description": "My favourite customer is just reading this text ☺️"
    }'
```

### Request fields

- `key` (required) - customer identifier, must be unique for a project (max 40 characters), 
- `description` (optional) - more details about the customer (max 255 characters),

### Example response
```json
{
  "msg": "OK",
  "status": 200,
  "data": {
    "key": "my-customer-2137",
    "description": "My favourite customer is just reading this text ☺️"
  }
}
```


## <span class="badge badge-primary">GET</span> Get one customer

```http request
https://api.simplelocalize.io/api/v1/customers/{customerKey}
```

### Example cURL

```shell
curl 
    --location 
    --request GET 'https://api.simplelocalize.io/api/v1/customers/{customerKey}' \
    --header 'X-SimpleLocalize-Token: <API_KEY>' \
    --header 'Content-Type: application/json'
```

### Example response
```json
{
  "msg": "OK",
  "status": 200,
  "data": {
    "key": "my-customer-2137",
    "description": "My favourite customer is just reading this text :)"
  }
}
```

## <span class="badge badge-primary">GET</span> Get all customers

Endpoint returns all available customers in the project.

```http request
https://api.simplelocalize.io/api/v1/customers
```

### Example cURL

```shell
curl 
    --location 
    --request GET 'https://api.simplelocalize.io/api/v1/customers' \
    --header 'X-SimpleLocalize-Token: <API_KEY>' \
    --header 'Content-Type: application/json'
```

### Example response
```json
{
  "msg": "OK",
  "status": 200,
  "data": [
    {
      "key": "my-customer-2137",
      "description": "My favourite customer is just reading this text :)"
    },
    {
      "key": "my-customer-1004",
      "description": "Some description for my-customer-1004"
    }
  ]
}
```


## <span class="badge badge-info">PATCH</span> Update customer

```http request
https://api.simplelocalize.io/api/v1/customers/{customerKey}
```

### Example cURL

```shell
curl 
    --location 
    --request PATCH 'https://api.simplelocalize.io/api/v1/customers/my-customer-2137' \
    --header 'X-SimpleLocalize-Token: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "key": "my-customer-2137-modified",
        "description": "My favourite customer is just reading this text ☺️"
    }'
```

### Example response
```json
{
  "msg": "OK",
  "status": 200,
  "data": {
    "key": "my-customer-2137-modified",
    "description": "My favourite customer is just reading this text :)"
  }
}
```

## <span class="badge badge-danger">DELETE</span> Delete customer

```http request
https://api.simplelocalize.io/api/v1/customers/{customerKey}
```

### Example cURL

```shell
curl 
    --location 
    --request DELETE 'https://api.simplelocalize.io/api/v1/customers/my-customer-2137' \
    --header 'X-SimpleLocalize-Token: <API_KEY>' \
    --header 'Content-Type: application/json'
```

### Example response
```json
{
  "msg": "OK",
  "status": 200
}
```


Customer API


One of the most common JSON format for apps and software localization is JSON file with all translations as shown below.
It's easy to use because you can fetch only one file and use all translations.

### File format example

```json
{
  "de": {
    "SALE": "Verkauf",
    "ADDRESS": "Adresse"
  },
  "fr": {
    "SALE": "soldes",
    "ADDRESS": "adresse"
  }
}
```

You can also use [single-language-json format](/docs/file-formats/single-language-json) to download only needed
translation messages for requested language key.

SimpleLocalize also recognizes nested JSON keys like shown below.

```json
{
  "de": {
    "SALE": {
      "NESTED": "Verkauf"
    }
  }
}
```

Above JSON will result with `SALE.NESTED` translation key.


## Upload with CLI

```properties
simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat multi-language-json \
  --uploadPath ./translations.json
```

Learn more about [SimpleLocalize CLI and translations upload](/docs/cli/upload-translations/) feature.

## Download with CLI

```properties
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat multi-language-json \
  --downloadPath ./translations.json
```

Learn more about [SimpleLocalize CLI and translations download](/docs/cli/download-translations/) feature.

## Import with API

```shell
curl
    --request POST \
    --url 'https://api.simplelocalize.io/api/v2/import?uploadFormat=multi-language-json' \
    --header 'x-simplelocalize-token: <API_KEY>' \
    --form file=@/path/to/your/file.json
```

Learn more about [importing translations with API](/docs/api/import-translations/)

## Export with API

```shell
curl
    --request GET \
    --url https://api.simplelocalize.io/api/v3/export?downloadFormat=multi-language-json \
    --header 'x-simplelocalize-token: <API_KEY>'
```

Learn more about [exporting translations with API](/docs/api/export-translations/)



JSON - Multi Language



The most popular office program can now be a tool for translation management. Localize you application with Microsoft Excel or any other spreadsheet tool.
Translations and translation keys can be exported using Web client, API or CLI to the Excel spreadsheet. You can share
the file with others and import it later to update the translations. Use Excel as a localization tool!

### File format example

![excel localization tool](/docs/excel-localization.png)

[Download Excel example file](/docs/simplelocalize-example.xlsx)

[Download Excel template file](/docs/simplelocalize-template.xlsx)


### Blocking translations

Using Excel files you can block specific keys and translations from being changed. In order to block specific translation key and its translations
add column named `OPTIONS` and put `BLOCK_MODIFICATION` text into the row which should be blocked in translation editor.

> Please make sure there is no spaces in the beginning or in the end of values in the Excel file.

#### Usage example
![Block translation in Excel file](/docs/excel-block-translation.png)

#### Blocked translation and key in List View
![Blocked translation in translation editor in list view](/docs/translation-editor-block-translation-list-view.png)

#### Blocked translation and key in Table View
![Blocked translation in translation editor in table view](/docs/translation-editor-block-translation-table-view.png)

Supported options:
- `BLOCK_MODIFICATION` - blocks option to edit translation and key (delete is still available)

If you need any custom function then please [let us know](/docs/general/support/). 

## Upload with CLI

```properties
simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat excel \
  --uploadPath ./my-excel-file.xlsx
```

Learn more about [SimpleLocalize CLI and translations upload](/docs/cli/upload-translations/) feature.

## Download with CLI

```properties
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat excel \
  --downloadPath ./my-excel-file.xlsx
```

Learn more about [SimpleLocalize CLI and translations download](/docs/cli/download-translations/) feature.

## Import with API

```shell
curl
    --request POST \
    --url 'https://api.simplelocalize.io/api/v2/import?uploadFormat=excel' \
    --header 'x-simplelocalize-token: <API_KEY>' \
    --form file=@/path/to/your/my-excel-file.xlsx
```

Learn more about [importing translations with API](/docs/api/import-translations/)

## Export with API

```shell
curl
    --request GET \
    --url https://api.simplelocalize.io/api/v3/export?downloadFormat=excel \
    --header 'x-simplelocalize-token: <API_KEY>'
```

Learn more about [exporting translations with API](/docs/api/export-translations/)



Excel file


CSV is the simples file format which can be used to upload translation keys from your project. Create a file with `.csv`
extension, and put there all translation keys which you can find in your project. Every translation key should be
separated with `;` or `,`.

### File format example

```css
email.user.hello; email.team;email.broken.button.instruction;email.user.created.subject
```

![translation keys in csv file](/docs/translation-keys-in-csv.png)

## Upload with CLI

```properties
simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat csv \
  --uploadPath ./my_keys.csv
```

Learn more about [SimpleLocalize CLI and translations upload](/docs/cli/upload-translations/) feature.

## Download with CLI

You cannot download translations in CSV format but you can download translation keys. If you want to download
translations consider using different file format like [JSON](/docs/file-formats/multi-language-json)
or [YAML](/docs/file-formats/yaml).

```properties
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat csv \
  --downloadPath ./translation-keys.csv
```

Learn more about [SimpleLocalize CLI and translations download](/docs/cli/download-translations/) feature.

## Import with API

```shell
curl
    --request POST \
    --url 'https://api.simplelocalize.io/api/v2/import?uploadFormat=csv' \
    --header 'x-simplelocalize-token: <API_KEY>' \
    --form file=@/path/to/your/file.csv
```

Learn more about [importing translations with API](/docs/api/import-translations/)

## Export with API

```shell
curl
    --request GET \
    --url https://api.simplelocalize.io/api/v3/export?downloadFormat=csv \
    --header 'x-simplelocalize-token: <API_KEY>'
```

Learn more about [exporting translations with API](/docs/api/export-translations/)



CSV file


One of the most common formats used in all Java and JVM apps for localization are property files as shown below. Every
file contains translations for a different language translations. It's a common case where those files have naming
convention like `messages_{language}.properties`. For example: `messages_pl-PL.properties`.

![java i18n properties file structure](/docs/java-properties-i18n-file-structure.png)

Such files are often used together
with [Thymeleaf template engine](https://www.thymeleaf.org/doc/tutorials/3.0/thymeleafspring.html#spring-mvc-configuration)
and for e-mail translations.

### File format example

```properties
# common
email.user.hello=Hello, {0}
email.team=SimpleLocalize.com Team
email.broken.button.instruction=In case the button link doesn't work for you, please copy and paste the link in your browser
# user created
email.user.created.subject=Setup password for SimpleLocalize account
email.user.created.instruction.button=In order to set up a new password, click on the button below:
email.user.created.button.text=Setup password
```

## Upload with CLI

```properties
simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat java-properties \
  --uploadPath ./messages_{lang}.properties
```

Learn more about [SimpleLocalize CLI and translations upload](/docs/cli/upload-translations/) feature.

## Download with CLI

```properties
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat java-properties \
  --downloadPath ./messages_{lang}.properties
```

Learn more about [SimpleLocalize CLI and translations download](/docs/cli/download-translations/) feature.

## Import with API

```shell
curl
    --request POST \
    --url 'https://api.simplelocalize.io/api/v2/import?uploadFormat=java-properties' \
    --header 'x-simplelocalize-token: <API_KEY>' \
    --form file=@/path/to/your/messages.properties
```

Learn more about [importing translations with API](/docs/api/import-translations/)

## Export with API

```shell
curl
    --request GET \
    --url https://api.simplelocalize.io/api/v3/export?downloadFormat=java-properties \
    --header 'x-simplelocalize-token: <API_KEY>'
```

Learn more about [exporting translations with API](/docs/api/export-translations/)



Java properties


PHP Arrays are simple objects which can contain simple key-value entries. Where key is treated as unique translation key, and
value which is translated message. One PHP file array contains language translations for only on language. For example: 
`messages_de_DE.php` contains translated message for German (Germany) locale.

### File format example

```php
<?php
    return [
        "HELLO_WORLD" => "Hello world!",
        "MY_TRANSLATION_KEY" => "This is my translation message!"
    ];
?>
```

## Upload with CLI

```properties
simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat php-array \
  --uploadPath ./messages_{lang}.php
```

Learn more about [SimpleLocalize CLI and translations upload](/docs/cli/upload-translations/) feature.

## Download with CLI

```properties
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat php-array \
  --downloadPath ./messages_{lang}.php
```

Learn more about [SimpleLocalize CLI and translations download](/docs/cli/download-translations/) feature.

## Import with API

```shell
curl
    --request POST \
    --url 'https://api.simplelocalize.io/api/v2/import?uploadFormat=php-array&languageKey=en' \
    --header 'x-simplelocalize-token: <API_KEY>' \
    --form file=@/path/to/your/messages.php
```

Learn more about [importing translations with API](/docs/api/import-translations/)

## Export with API

```shell
curl
    --request GET \
    --url https://api.simplelocalize.io/api/v3/export?downloadFormat=php-array \
    --header 'x-simplelocalize-token: <API_KEY>'
```

Learn more about [exporting translations with API](/docs/api/export-translations/)



PHP Array


A common format used in Android localization and translation is XML. Regular `strings.xml` files keep translation keys
in `name` attribute and the value of `<string></string>` tag is a localized message.

Values from `strings.xml` can be used in Android Java code using a reference `R.string.string_name`. You can also access
localized strings in your XML layout files by using `@string/string_name`. The `string_name` value used in examples is a
translation key.

### File format example

```xml
<resources>
    <string name="app_name" translatable="false">SimpleLocalize.io</string>
    <string name="welcome_message">Welcome in SimpleLocalize!</string>
    <string name="save_button">Save</string>
    <string name="back_button">Back</string>
</resources>
```

Every `string.xml` file sits in separate `values-{lang}` directory like shown below.

![android localization files structure](/docs/android-resource-values.png)

> We have special integration for Android! See [Android - quick integration guide](/docs/integrations/android) to make your
> work with this platform less time-consuming.

## Upload with CLI

```properties
simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat android \
  --uploadPath ./values-{lang}/strings.xml
```

Learn more about [SimpleLocalize CLI and translations upload](/docs/cli/upload-translations/) feature.

## Download with CLI

You cannot download translations in CSV format. In example below we put `excel` format which allow you to see all the
translations and translation keys in spreadsheet format.

```properties
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat android \
  --downloadPath ./values-{lang}/strings.xml
```

Learn more about [SimpleLocalize CLI and translations download](/docs/cli/download-translations/) feature.

## Import with API

```shell
curl
    --request POST \
    --url 'https://api.simplelocalize.io/api/v2/import?uploadFormat=android' \
    --header 'x-simplelocalize-token: <API_KEY>' \
    --form file=@/path/to/your/strings.xml
```

Learn more about [importing translations with API](/docs/api/import-translations/)

## Export with API

```shell
curl
    --request GET \
    --url https://api.simplelocalize.io/api/v3/export?downloadFormat=android \
    --header 'x-simplelocalize-token: <API_KEY>'
```

Learn more about [exporting translations with API](/docs/api/export-translations/)



Android XML


Localization on macOS and iOS looks very similar. Both platforms share the same concepts, programming language and
localization approach. In Swift world the most commonly used localization format for messages are *.strings files.
Each *.strings file contains translated messages and sits in separate directory. Like shown below

![macos and ios localizable strings](/docs/localizable-strings.png)

Translations format is straightforward. The first value is a translation key used by a programmer during software
development, and the second is a translated message which will be visible for end user.


### File format example

```json
"Access denied!" = "¡Acceso denegado!";
"Accurate to approx. 15 decimal places" = "Accurate to approx. 15 decimal places";
"Accurate to approx. 7 decimal places" = "Accurate to approx. 7 decimal places";
```

## Upload with CLI

```properties
simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat localizable-strings \
  --uploadPath ./{lang}/Localizable.strings
```

Learn more about [SimpleLocalize CLI and translations upload](/docs/cli/upload-translations/) feature.

## Download with CLI

```properties
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat localizable-strings \
  --downloadPath ./{lang}/Localizable.strings
```

Learn more about [SimpleLocalize CLI and translations download](/docs/cli/download-translations/) feature.

## Import with API

```shell
curl
    --request POST \
    --url 'https://api.simplelocalize.io/api/v2/import?uploadFormat=localizable-strings' \
    --header 'x-simplelocalize-token: <API_KEY>' \
    --form file=@/path/to/your/Localizable.strings
```

Learn more about [importing translations with API](/docs/api/import-translations/)

## Export with API

```shell
curl
    --request GET \
    --url https://api.simplelocalize.io/api/v3/export?downloadFormat=localizable-strings \
    --header 'x-simplelocalize-token: <API_KEY>'
```

Learn more about [exporting translations with API](/docs/api/export-translations/)



Localizable Strings


Gettext is a commonly used system for software localization and internationalization. It was realised initially in 1990, 
and it's still widely used in many Unix-like systems. Thanks to gettext you can easily separate source 
code logic from texts in your application.

We can distinguish 2 different file formats:
- POT file format, acronym stands for Portable Object Template which is used as a template for translating 
  text, it does not contain translated messages, only message ids, comments, and contexts. You can treat it as a template.
- PO file format, acronym stands for Portable Object which is a translation record which contains same 
  values like POT file, but it also contains translated strings for single language.

### File format example  

```text
# Single line
msgctxt "Translation context"
msgid "Translation key"
msgstr "Translation message"

# Multiple lines
msgid ""
"The input text "
"split to several "
"lines"
msgstr ""
"Translation "
"can also be splitted."
```

### Example gettext usage

```cpp
printf(gettext("Hello world! I'm %s.\n"), application_title);
printf(_("Hello world! I'm %s.\n"), application_title); // shorter version
```

## Upload with CLI

```properties
simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat po-pot \
  --uploadPath ./messages_{lang}.po
```

Learn more about [SimpleLocalize CLI and translations upload](/docs/cli/upload-translations/) feature.

## Download with CLI

```properties
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat po-pot \
  --downloadPath ./messages_{lang}.po
```

Learn more about [SimpleLocalize CLI and translations download](/docs/cli/download-translations/) feature.

## Import with API

```shell
curl
    --request POST \
    --url 'https://api.simplelocalize.io/api/v2/import?uploadFormat=po-pot&languageKey=en' \
    --header 'x-simplelocalize-token: <API_KEY>' \
    --form file=@/path/to/your/messages.po
```

Learn more about [importing translations with API](/docs/api/import-translations/)

## Export with API

```shell
curl
    --request GET \
    --url https://api.simplelocalize.io/api/v3/export?downloadFormat=po-pot \
    --header 'x-simplelocalize-token: <API_KEY>'
```

Learn more about [exporting translations with API](/docs/api/export-translations/)



Gettext - PO/POT


CommonJS uses `module.exports` syntax to load various data. One of them are localization files. File format looks 
very similar to the standard JSON file, but it starts with `module.exports = ` and it's saved as `JavaScript` with `.js` extension.

### File format example

```js
module.exports = {
  "HELLO_WORLD": "Hello world!",
  "TRANSLATION_KEY": "This is my translated text!"
}
```

## Upload with CLI

```properties
simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat module-exports \
  --uploadPath ./messages_{lang}.js
```

Learn more about [SimpleLocalize CLI and translations upload](/docs/cli/upload-translations/) feature.

## Download with CLI

```properties
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat module-exports \
  --downloadPath ./messages_{lang}.js
```

Learn more about [SimpleLocalize CLI and translations download](/docs/cli/download-translations/) feature.

## Import with API

```shell
curl
    --request POST \
    --url 'https://api.simplelocalize.io/api/v2/import?uploadFormat=module-exports&languageKey=en' \
    --header 'x-simplelocalize-token: <API_KEY>' \
    --form file=@/path/to/your/file.js
```

Learn more about [importing translations with API](/docs/api/import-translations/)

## Export with API

```shell
curl
    --request GET \
    --url https://api.simplelocalize.io/api/v3/export?downloadFormat=module-exports \
    --header 'x-simplelocalize-token: <API_KEY>'
```

Learn more about [exporting translations with API](/docs/api/export-translations/)



CommonJS - module.exports


Many i18n libraries uses YAML files to keep translation messages. One of libraries which uses YAML format is
[jekyll-multiple-languages-plugin](https://github.com/kurtsson/jekyll-multiple-languages-plugin) created
by [Martin Kurtsson](https://github.com/kurtsson). SimpleLocalize supports yaml format to import and export
translations. You can use nested translations keys like shown below.

### File format example

```yaml
my-translation-key: My localized message
look:
  at:
    this: Look at this!
  this:
    is:
      also:
        supported: Look this is also supported!
```

Such example will produce 3 different translation keys in translation editor.

## Upload with CLI

```properties
simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat yaml \
  --uploadPath ./translations_{lang}.yaml
```

Learn more about [SimpleLocalize CLI and translations upload](/docs/cli/upload-translations/) feature.

## Download with CLI

```properties
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat yaml \
  --downloadPath ./translations_{lang}.yaml
```

Learn more about [SimpleLocalize CLI and translations download](/docs/cli/download-translations/) feature.

## Import with API

```shell
curl
    --request POST \
    --url 'https://api.simplelocalize.io/api/v2/import?uploadFormat=yaml' \
    --header 'x-simplelocalize-token: <API_KEY>' \
    --form file=@/path/to/your/file.yaml
```

Learn more about [importing translations with API](/docs/api/import-translations/)

## Export with API

```shell
curl
    --request GET \
    --url https://api.simplelocalize.io/api/v3/export?downloadFormat=yaml \
    --header 'x-simplelocalize-token: <API_KEY>'
```

Learn more about [exporting translations with API](/docs/api/export-translations/)



Table of content

CLI: Get started

Installation

Usage

SimpleLocalize CLI commands

SimpleLocalize CLI Authorization

Get Involved