Learn how projects, keys, platforms and files are organized.

Ilya Krukowski avatar
Written by Ilya Krukowski
Updated over a week ago


Lokalise is a project-based translation management system. A project is a collection of languages, keys, translations values, screenshots attached to these keys, contributors who have access to this project, as well as settings.

Usually a single project contains translations for a single application, website, or a game. We recommend keeping keys and translations for all platforms (for example, web and mobile) in a single project for your own convenience. Upload iOS, Android, frontend, backend, and API language files – everything that relates to a certain app or website – to the same project. We provide you with key merging or referencing options that help you avoid repetitive work for translators.

Every project belongs to exactly one Lokalise team. A team is a collection of projects, team users, and settings. Every team has a separate subscription plan.

With this in mind, we can construct a simple hierarchy:

  • Team

    • Settings

    • Subscription plan

    • Team users (can participate in one or more projects)

    • Project

      • Languages

      • Translation keys

        • Translation values (one translation per language)

      • Settings

      • Contributors

      • Tasks

      • Screenshots

      • Snapshots (backups)

You can see that a project belongs to a team, whereas keys belong to a single project, and can contain one or more translation values for different languages.

Creating a new project

Every team member with proper access rights (owner, biller, admin) can create projects within a team. Lokalise allows you to create an unlimited number of projects but please be aware of other team quotas — specifically, the number of keys you can create.

To create a project, open the main dashboard and click New project:

Please note that every project is created from scratch and currently we do not provide a feature like "project templates". What you can do, however, is create a project snapshot and then restore it thus creating a project copy.

Choosing project type

After pressing New project, you'll be asked to choose the project type:

Currently we support three project types:

  • Web and mobile — choose this type if you are working with translation files in a key-value format (.json, .yaml, .strings, .xlsx) or if you're looking to connect with services like GitHub, Wordpress, or Figma.

  • Marketing and support — choose this type if you're looking to exchange and translate content from services like Iterable, Marketo, Contentful, Zendesk, Salesforce, and others.

  • Ad doc documents — choose this type if your content is stored in text files like .docx, .pptx, .html, or .idml.

You can find all the supported file formats in the corresponding articles collection. Please note that you cannot change the type after the project is created.

Adjusting project options

After choosing the project type, you'll be presented with the following dialog:

Let's discuss the available options (most of these can be adjusted after the project is created):

  • Project name — enter the name of your translation project. This name will be visible to other project contributors.

  • Base language — this is the "main" language of your project, the language you are going to be translating from.

  • Target languages — choose one or more languages that you would like to translate into.

  • Segmentation — this feature is not available for the Marketing and support projects. When enabled, your translations uploaded to the project will be split into smaller, relevant chunks. It's quite convenient when translating longer texts. Upon downloading translations, these segments will be automatically combined into a single translation string.

    • Please note that you cannot enable or disable segmentation after the project is created.

    • Also keep in mind that segmented projects do not support branching therefore if you were planning to take advantage of this feature, do not enable segmentation.

  • Content integration — this option is available only for the Marketing and support projects. Use this dropdown to pick a third-party service to integrate with.

Once you are ready, click Create project and a new project will be created for you!

Project ID

Each project has a unique alphanumeric ID that is generated for you upon project creation. Each project URL contains this ID, for example:

You can also find this ID in the project settings:

Please note that the project ID cannot be modified.

This ID is used when referring to a project with Lokalise API or CLI. If you are not planning to use these developer tools then most likely you won't need the project ID and knowing only its name should be enough.

I've created a project: what's next?

That's a good question! The further steps will highly depend on what you are trying to achieve. Let's explore some options.

Adjust project settings

You might want to adjust your project settings. To achieve that, click More > Settings in the top menu:

Here you can change your project name, description, enable or disable additional features, create project snapshots (backups), set up automation rules, and perform other actions. Please check the Project settings article to learn more.

Upload translation files

After project settings are adjusted, you will probably want to upload your content to start translating. To achieve that, proceed to the Upload page:

Here on this page you'll need to choose one or more files to upload and adjust the uploading settings. Please find detailed instructions in the corresponding article.

Add more project languages

When creating the project, you have already chosen one base language and one or more target languages. Also, when you are uploading translation files, all missing languages will be created automatically in your project. However, you might still need to add even more languages and this is a very simple thing to do.

Click on the Languages dropdown and choose New language:

Then choose one or more languages from the dropdown and click Add:

Later you can adjust language settings as explained in the corresponding article.

Get yourself familiar with the project editor

Once you've uploaded one or more translation files, you can return to the project editor:

There's a lot going on here and it might take some time to get used to. We would recommend checking out the following article to learn about the editor and the features it provides for you.

Learn how keys, platforms, and files are organized

One important question is: what happens once my translation file is uploaded to Lokalise? How my data will be stored and organized?

First of all, let's discuss some important terminology:

  • Translation file — a file that contains your translation data. It can be a regular .docx file or a .json file that stores data in a key-value format.

  • Translation key — this term is generally used when talking about key-value formats. A key acts as a placeholder in the application source code and is replaced with the corresponding translation value when the app is served to the end user. The actual value depends on the user's locale preferences. For example, your app's source code can have an index.hello key, and this key has two translation values stored inside separate files: "Hello" (for English) and "Sveiki" (for Latvian). Finally, when the app is served to the user the index.hello key is replaced with one of the values depending on what locale the user has requested.
    The idea is slightly different when talking about .docx, .pptx, and other document-type files that do not employ the key-value storage. In this case Lokalise automatically generates some alphanumeric identifiers for every part of the document. For example, we can say that every paragraph in a Word document is a single "key". Or perhaps every PowerPoint slide item (heading, subheading, text) is also a key.

  • Translation value — a value is basically a string of text translated into a single language. One translation key can have multiple translation values depending on how many languages you are planning to support. So, if your Lokalise project has five languages, then every translation key will have five translation values.

  • Platform — in terms of Lokalise, a platform is an attribute that can be assigned to a translation key. There are four platforms: Web, iOS, Android, Other. Each key must belong to at least one platform but nothing prevents you from assigning a single key to multiple platforms. This is very convenient when you have both Web and mobile app, and the same translations should be used in both apps.
    Speaking simply, a platform determines which file formats the key will be exported for. Thing is, when you are going to download translations from Lokalise back to your PC, you'll have to choose an output file format, and our platform currently supports 20+ formats. These formats are separated by platform, so for example .json is a Web format, whereas .strings is an iOS format.
    Therefore, if a key belongs to the Web platform, it will be exported when the .json format is chosen but it will be ignored when the .strings format is utilized (however there's a way to override this behavior).

You can find more information on keys and platforms in the corresponding document.

So, what exactly is going to happen when you upload your translation files to Lokalise? We'll parse these files and extract all key-value pairs along with additional attributes (comments, descriptions, extra attributes). Based on the file format, keys will be assigned to the corresponding platforms.

If you are uploading a Word file then we'll split text into paragraphs, and each paragraph will act as a key. A similar thing will happen for other Document file types.

Keys and values will be displayed in the following way:

So, what's going on here?

  • api is your translation key. Clicking on the key name will bring up a key editor that can be used to adjust key options.

  • The Android icon means that this key is assigned to the Android platform, and the Chrome icon means that is assigned to the Web platform. Click on these icons to add or remove key platforms.

  • Click on the small label icon to add or remove key tags. One the screenshot above the key has an "API" tag. You can use tags to filter your translation keys.

  • %LANG_ISO%.json is the filename that this key belongs to. Initially I've uploaded two translation files named en.json (English) and fr.json (French). en and fr are valid locale ISO codes therefore Lokalise detected those and automatically replaced these codes with a special %LANG_ISO% placeholder. Now, when downloading my translations back, I'll be able to split those into separate translation files based on the language. These files will use the %LANG_ISO%.yaml name but the %LANG_ISO% placeholder will be replaced with the actual language code. In other words, when downloading English and French translations, I'll get en.json and fr.json once again.
    Click on the key name to bring up the key editor where you can manage key filenames.

  • To the right, you can see English and French translations. Both are linked to the api key. Click on one of the translations to edit it.

Now we can create a simple hierarchy:

  • Translation key

    • Name

    • Description

    • Translation values (one value per language)

    • Platform(s)

    • Filenames (please note that filenames can contain multiple keys)

    • Tags (tags can contain multiple keys)

Invite contributors to the project

If you're working with a team, then you'll need to invite more people to the project, right? To achieve that, proceed to the Contributors page:

Here you'll be able to add one or more people to the project and adjust their access rights. Please find more info in the corresponding article.

Assign tasks to the contributors

Now that the contributors are invited, you'll probably want to assign some work to them. Therefore proceed to the Tasks page:

On this page you'll be able to create a new task, choose translations to include and contributors to assign this task to. Please find more information in the Tasks article.

Use Lokalise apps

If your content was initially hosted on a third-party platform, say GitHub repo, Wordpress website, or Zendesk Guide you'll probably need an easy way to perform content exchange. That's why we've introduced Lokalise apps that enable you to connect with numerous services and tools easily. To get started, proceed to the Apps page:

Choose one of the apps and install it! Please find more information on our apps in the corresponding section.

Download translations back to your project

After you're done working with translations, you'll probably want to download them back to your project. Therefore, proceed to the Download page:

Here you'll need to choose an output file format, the language to include, and adjust other options. Please refer to the following article to learn more about file downloading and all the available options.

My project is empty and I see a message that it was archived!

We archive inactive teams and the corresponding projects on a regular basis. However, all your data is still preserved: please check this article to learn more about this process and how you can unarchive your projects.

Did this answer your question?