
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...
```

## Localization CLI Tool Features:

- [extract i18n keys from project files](/docs/cli/i18n-keys-extraction)
- [upload translations or keys from disk](/docs/cli/upload-translations)
- [download translations to disk in desired format](/docs/cli/download-translations)
- manage deployment (soon!)
- bring your i18n library of choice
- vendor agnostic

## 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


![translation management](/docs/simplelocalize-options.jpg)

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

- [**CLI: Extract translation keys**](/docs/cli/get-started): extract i18n keys from your application code,
- [**CLI: Upload translations**](/docs/cli/upload-translations): upload translation files from your project files,
- [**CLI: Download translations**](/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,
- [**Host translations for live updates**](/docs/general/translation-hosting): publish translations and access them using CDN,
- [**Get started with REST API**](/docs/cli/get-started): use our free REST API to manage translations right away,
- [**Integrate any library**](/integrations): use the service with any i18n library like i18next, FormatJS by fetch plain JSON file with your translations,
- **Excel export & import**: export translations into Excel spreadsheets and import again to make changes.
  

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

## Happy coding!


Introduction


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. Check [API endpoint for importing translations](/docs/api/import-translations).
You can also upload translations using the web client. For integration purposes we can also recommend configuring [CLI upload](/docs/cli/upload-translations).

![upload file formats supported by localization software](/docs/upload-file-formats.png)

## Web client import

In order to import using a web client, please go to the 'Data' tab and scroll down to section 'Import data'.

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

All imports are performed in the background and in some cases it may take a while to import a file. 
You can see an import result in the 'Activity' tab.

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


Import translations


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


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. 

## 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)

## How to add 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 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 languages

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.

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


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


## 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)


## Extract translations keys and configure live updates

This guide will show you how to extract translation keys from local project files. In the second part you will focus on
configuring real-time translation updates.


## 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

Use SimpleLocalize CLI to extract and upload all translation keys from your project. CLI will find all usages of `t('KEY')` in your files and add them to the project.

```properties
simplelocalize extract \
  --apiKey <PROJECT_API_KEY> \
  --projectType i18next/i18next \
  --searchDir ./src
```

Learn more about [message extraction from project files](/docs/cli/i18n-keys-extraction).

## Translate your messages

Now you can use translation editor to add localized messages for each key.

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

## Translation hosting

Let's focus now on integrating [translation hosting](/docs/general/translation-hosting) to use translated messages in your application.

### Install dependencies

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

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

### 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'

const projectToken = "5e13e3019cff4dc6abe36009445f0883";
const loadPath = `https://cdn.simplelocalize.io/${projectToken}/_latest/i18next/{{lng}}/{{ns}}/_index`;

i18n
  .use(Backend)
  .use(LanguageDetector)
  .use (initReactI18next)
  .init({
    // default/fallback language 
    fallbackLng: 'en',
    ns: ["default"],
    defaultNS: "default",
    //detects and caches a cookie from the language provided
    detection: {
      order: ['queryString', 'cookie'],
      cache: ['cookie']
    },
    interpolation: {
      escapeValue: false
    },
    backend: {
      loadPath
    }
  })

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` object 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


## 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


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


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


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

```properties
simplelocalize upload \
 --apiKey PROJECT_API_KEY \ 
 --uploadPath ./my-messages.json \ 
 --uploadFormat single-language-json
 --languageKey en
```
## 📦 Upload formats

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

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

## 📦 Download formats

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
```


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

```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
```

### Available upload formats

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 import options

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)

## 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

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

### Available download file formats

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

## 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



Export translations


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
```

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

## Download with CLI

```properties
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat simplelocalize-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=simplelocalize-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=simplelocalize-json \
    --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


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)

## 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

Localization CLI Tool Features:

CLI Authorization

Get Involved