In this document, you'll find all the information you need to know about the changes to the permission management system on Lokalise that we're introducing.

TL;DR

Lokalise is updating its permission management system to improve control over user actions, enhance workflow efficiency, and ensure better security. These changes address important areas to make your experience smoother and more reliable.

Why this change is beneficial?

Improved role management: Previously, assigning a contributor the project admin role allowed them to edit the source text and translations in all languages. The new system ensures more precise role definitions, reducing the risk of unreviewed changes.
Controlled high-impact actions: The old system lacked control over which users could execute high-impact actions. The new system provides better control, ensuring only authorized users can perform these critical tasks.
Stable integrations: When an API token owner is removed from a Lokalise team, the integrations connected to that token will stop working. The new system provides a warning before you remove a user who owns an API token, allowing you to plan ahead and maintain integration continuity.
Enhanced efficiency for regular users: Regular users couldn't execute bulk actions in the Editor, limiting their efficiency. The new system grants these users the ability to perform bulk actions, streamlining their workflow.

When will these changes be rolled out?

The updates to the permission management system are being implemented gradually, starting in October 2024. This phased rollout ensures a smooth transition and provides time to make any necessary adjustments along the way.

Your team may not yet be affected by these changes. To check which permission system your team is using, open one of the projects within the team, go to the Contributors page, and review the interface displayed there.

The old UI

The new UI

How the permissions system worked before this change?

Previously, to get a user working on a project, you needed to add them as a contributor.

Here’s how it worked:

Language access: You specified which languages the contributor could view and edit.
Additional permissions: Optionally, you could grant them extra permissions to review translations or administer the project.

Team owners were always included as contributors in projects by default.

How will contributor management work now?

We’re giving the Contributors page a complete overhaul, making the whole management process way more convenient. You’ll still add contributors to your project as usual (and team owners are still part of every team project), but now it’s a lot easier to fine-tune their roles and permissions.

Key changes:

Editable languages: Previously called "contributable languages," these are the languages contributors can modify.
Readable languages: Formerly known as "reference languages," these are the languages contributors can only view without making changes.
Roles and granular permissions: When adding new contributors, you can assign one of the predefined roles. Each role has a specific set of permissions (for example, a Content creator can manage keys, screenshots, languages, and view activity). But if you need more control, you can customize these permissions further after the contributor has been added.

To fine-tune permissions, click the "more" icon under the Actions column and select Edit permissions.

From there, you’ll see a dialog box:

On the left, choose one of the predefined roles to start with. Alternatively, choose Custom to fully customize assigned permissions.
On the right, tweak specific permissions as needed.

Once you’re done, hit Save permissions to apply the changes.

Available roles and permissions

We currently offer five built-in roles, each with its own set of permissions:

Manager — has the highest access rights. Managers can perform all actions within the project.
Developer — manages translation keys and handles file uploads/downloads. Permissions include:
- Manage keys
- Manage screenshots
- View activity
- Upload files
- Download files
Content creator — manages keys and languages. Permissions include:
- Manage keys
- Manage screenshots
- Manage languages
- View activity
Reviewer — focuses on checking and approving translations. Permissions include:
- Review
- Change custom status
Translator — the most restrictive role. Translators can only view and edit the languages assigned to them. They don’t have any additional permissions by default.

How will the contributor invite flow work?

To add a new contributor to your project, click the Add contributor button and fill in the following details:

Email addresses: Enter one or more email addresses, separated by commas.
Role: Select a predefined role that comes with a set of permissions. If needed, you can adjust these permissions later as described in the previous section.

Select languages: Choose which languages will be editable (read/write) and which will be readable (read-only) for the contributor.

Adding team members

You can also add contributors from Team settings > Team.

The Add team users dialog has been updated. Here’s what to do:

Enter email addresses: Provide one or more email addresses.
Select project: Choose the project you want to add these users to.
Role: Pick one of the predefined roles.
Select languages: Decide which languages will be editable and which will be read-only.

After you hit Add team user, the contributors will be added to the project with the chosen permissions. They’ll also join your team as members, which means they can work on projects but can’t modify team settings.

How will importing from an existing project work?

To bring in contributors from another team project, click the Import from project button. In the dialog that appears, select the project you want to copy users from.

By default, all contributors from the selected project will be imported, but you can uncheck any contributors you don’t want to add to the current project.

How will user groups work?

User groups remain mostly unchanged, but we’ve revamped the Permissions tab.

You can now fine-tune permissions for each group member, giving you more flexibility and control over group settings.

Important notes:

If a user is added to a project through multiple groups, they will receive all the permissions from each group.
New: If a user is added to a project individually, they will only have the permissions assigned to them as an individual contributor. Permissions from user groups won’t apply in this case.

What happens to the project admins and reviewers?

With the new, more granular permissions system, we’ve retired the term "project admin." Now, every contributor will have a specific set of permissions that define what actions they can perform.

The "reviewer" role now includes review and change custom status permissions.

We’ve made sure that existing users in your projects keep their current permissions. If you spot any discrepancies, check the Audit logs or reach out to our support team for assistance.

How will the API be affected?

The API endpoints are being updated to align with the new permissions system. Each endpoint will now validate the caller’s specific permissions.

Key points to note:

Permission templates
- A new endpoint has been introduced for managing permission templates.
- Each template is identified by a role_id and includes a detailed list of assigned permissions.
- Use the List all permission templates for a particular team endpoint to retrieve a comprehensive list of available permissions.
Contributors and Team groups
- The is_admin and is_reviewer fields will continue to function as they do today but are deprecated and scheduled for eventual removal.
  - Action required: Plan to update your scripts to align with the new permissions system.
- The admin_rights field will now return a list of permissions derived from the new system.
  - This change is not backward-compatible. If your scripts rely on specific values returned by admin_rights (e.g., programmatically using individual permissions), review your code to accommodate the updated permissions format.
- A new role_id field (number) has been added to represent the permission template ID assigned to a contributor.
  - Use role_id as the key for identifying a contributor's permissions in the new system.

What will regular contributors be able to do without assigned permissions?

If you add a contributor without assigning any specific permissions (Translator role), they’ll still have access to some basic actions:

View translations: They can see translations for the languages marked as readable.
Modify translations: They can edit translations for the languages marked as editable. However, if they don’t have the "Contribute to master branch" permission, they can only make changes in non-master branches.
View project information: They’ll be able to see basic project details like base words, completion percentage, and total number of keys.
Manage comments: They can read, create, and delete their own comments.
Browse glossary: They can view glossary entries.
Generate API tokens: They can create personal API tokens.

Special notes on individual permissions

The new permissions system introduces dependencies between certain permissions and readable languages.

Project with branching enabled

Contribute to master: Contributors without this permission will be able to modify translations only within non-master branches. This permission will be automatically selected when any of the following permissions are granted:
- Merge branches
- Upload files
- Download files
- Manage keys
- Manage screenshots
- Manage languages
- Review translations
Create branches: When a user is assigned this permission, they will also receive the Merge branches permission.
All languages as contributable: Assigning a user all languages as contributable will also give them all languages as readable.
All languages: Selecting All languages (readable or editable) guarantees that the user will have access to any new languages added to the project later.

Permissions implying "All languages" readability

Certain permissions inherently grant the ability to read all languages to ensure proper functionality:

Manage keys: Necessary so the user knows the implications on the base language and translations when they move, copy, or delete keys.
Upload files: Necessary so the user can verify that all content is properly uploaded.
Download content: Necessary so the user can select which content to download.
Create branches: Necessary to see all the content that will be copied into the new branch.
Merge branches: Necessary to see all the content that will be merged into the master branch.
Manage tasks: Necessary to see all the content that can be translated, which is essential for task managers.
Manage settings: Those who manage project settings should see all the content in the project.
Manage languages: If a user can manage languages, they should be able to verify that the expected languages appear in the editor.

Glossary permissions

Delete glossary term: Assigning this permission also grants the ability to add and edit glossary terms.

Previously, all users could create and update glossary terms. Now, a new granular permission distinguishes between who can edit vs. delete glossary terms.

Permissions for design plugins and apps

To use design plugins (e.g., Figma or Adobe XD), specific permissions are required:

Team admin: Needed to create a new project directly from the plugin.
Manage languages, Manage screenshots, Manage keys: Required to run the plugin and interact with project data.
Contribute to master branch: Additionally required if the user needs to work within the master branch.

What is not changing?

Despite the updates, some aspects of the permission management system will remain the same:

User groups: No changes are being made to user groups.
Team roles: The roles of owners, billers, admins, and members will stay the same.

Onboarding guide for project managers