Troubleshooting common problems

Downloading translations

No changes detected

Typical symptom

Downloading translation files from Lokalise...
Starting download from Lokalise
Download complete! Detecting changed files...
No changes detected in translation files.

Most likely cause

There are two main causes:

• The action simply does not find any changes because the downloaded translations are identical to the ones already present in the repo.
• The action cannot properly compare changes due to misconfiguration and reports no changes. This usually happens when translations are extracted into unexpected locations and there is nothing to compare against.

How to fix

Check the bundle structure

First, it’s recommended to manually inspect the download bundle on Lokalise:

1. Open your Lokalise project.
2. Go to More → Activity.
3. Find the finished download process in the list.
4. Click More → Download to get the archive with all translations.

Carefully check:

• Overall bundle structure
  Make sure it matches your project structure on GitHub.
  Are there any unexpected nested directories? Any intermediate folders missing?
  For example, if your translations are stored in public/locales/en on GitHub, the same folder must be present in the bundle.
• Folder and file naming
  Are there any unexpected characters in names? Are any files missing?

Also make sure you’re assigning filenames to your keys on Lokalise correctly, as explained in the README. Issues with bundle structure and filenames are the most common cause of this problem. For example, if you are storing translations under locales/en/common.json, locales/fr/app.json, etc., then:

• Use locales as the translations_path
• Make sure the filenames assigned to your keys on Lokalise contain the %LANG_ISO% placeholder: locales/%LANG_ISO%/common.json.

Check important action inputs

• translations_path — This must contain one or more paths to your translation directories without filenames or %LANG_ISO% placeholders (those are replaced with locale codes by Lokalise during download). Translations are always extracted from the archive into the repo root, then placed according to the bundle structure. For example, if the download bundle contains the file pub/i18n/en/en.json but translations_path does not include pub/i18n, the action will not scan this directory and will not detect any changes.
• flat_naming — If your translation files are not separated by locale folders (e.g. locales/en.json instead of locales/en/file.json), you must set this input to true. By default this is disabled (false).
• file_ext — Try explicitly setting the file extensions to look for, e.g.:

file_ext: json

• skip_original_filenames — Enable this only if you don’t want to use the original filenames assigned to translation keys on Lokalise.
  When enabled:
  • All translations are grouped into files named after locale codes (en, fr, de, etc.).
  • Files are downloaded into the repo root by default.
  • If you want to adjust the download location, set the "directory_prefix" param in additional_params. For example:

# This will place the downloaded translations into the locales/ folder.
additional_params: >
  {
    "directory_prefix": "locales/"
  }

"No keys for export"

Typical symptom

Starting download from Lokalise
Error: download failed: fetch bundle: request (attempt 1): No keys for export with current export settings
Error: lokalise_download script failed with exit code 1

Most likely cause

Based on your current download settings, the Lokalise API cannot find any keys to include in the bundle. In other words, there is nothing to download. This usually happens when:

• You request a specific file format (using the file_format input), but no keys for this format can be found.
• You filter keys by some condition (for example, by tag), but the resulting set is empty.

How to fix

There are two main areas to check.

1. Platforms and file formats

First, check platforms assigned to your keys in Lokalise and make sure the requested file format is connected to that platform.

Examples:

• If you request the json file format, only keys assigned to the Web platform will be downloaded.
• If you request strings, only keys assigned to the iOS platform will be included in the bundle.

If no keys are assigned to the platform required by the chosen file format, the bundle will be empty.

To fix this:

• Assign the corresponding platforms to the relevant keys (via key editor or bulk actions) and re-run the action.
• Alternatively, for testing, you can set "all_platforms": true in additional_params to include all keys regardless of platform (not recommended for regular production usage).

2. Filters in your export settings

Next, check if any filtering is configured.

• Filtering by tag.

  • If the skip_include_tags input is not set to true, the action will filter keys by the tag named after the triggering branch on GitHub.
  • If the additional_params input contains the include_tags param (and skip_include_tags is disabled), filtering happens by the tags listed there.
    Learn more in the readme.

• Filtering by other criteria. Typically this is configured via additional_params. Watch for params like:

  • "export_empty_as": "skip"
  • filter_data
  • filter_langs
  • other filter_* or include_* / exclude_* options.

If filtering is enabled, try to disable it temporarily:

• Comment out any filtering-related params in additional_params.
• Set skip_include_tags: true.

Then re-run the action. If the download succeeds without filters, you’ve confirmed the issue is caused by your filters. Re-enable them one by one and re-run to identify which specific filter is excluding all keys.

I'm using Gettext (PO) and the PR is opened when only revisition date is changed

Typical symptom

You are using Gettext (PO files), the action opens pull requests when no translations have been changed and the only difference is the "revision date".

Most likely cause

The action cannot "understand" if the change is relevant or not. Once the file is changed, it will be added to a PR, even if the translations are not modified.

How to fix

Please refer to the following discussion to find a potential solution.

Authorization/Authentication

"Forbidden" when downloading translations

Typical symptom

Starting download from Lokalise
Error: download failed: fetch bundle: request (attempt 1): Forbidden
Error: lokalise_download script failed with exit code 1

Most likely cause

Your Lokalise project_id input is empty, malformed, or passed incorrectly (for example, a wrong secret/reference, missing quotes, or an unintended newline).

How to fix

• Verify that your Lokalise project ID is correct and contains no typos, spaces, or hidden characters. You can find the ID in the project settings.
• Make sure you’re passing the project ID through secrets/variables correctly.
• If you're using Lokalise branching, the branch name must be appended using the PROJECT_ID:BRANCH format:

project_id: "123.abc:develop"

"Invalid X-Api-Token header" when downloading translations

Typical symptom

Starting download from Lokalise
Error: download failed: fetch bundle: request (attempt 1): Invalid `X-Api-Token` header
Error: lokalise_download script failed with exit code 1

Most likely cause

Your Lokalise API token passed via the api_token input is either:

• missing required permissions,
• passed incorrectly from your secrets,
• expired or revoked.

How to fix

• Make sure your Lokalise API token has at least read permissions.
• API tokens are per-user, so verify that the user who generated this token has the required project permissions. They must have at least Download files permission.
• Store the token in repo/org secrets and pass it like this:

api_token: ${{ secrets.LOKALISE_API_TOKEN }}

• Double-check that:
  • The token belongs to a contributor that has access to the target Lokalise project.
  • The token is not revoked.
  • You're not passing an OTA token by mistake. OTA token are used for a different feature and they're created in the Lokalise project settings. API tokens are created under the personal profile.
  • You didn’t accidentally paste extra spaces or quotes into the secret value.

"Bad credentials" when creating/updating PR

Typical symptom

Failed to create or update pull request: Bad credentials
Commit created but no PR exists (unexpected).
Error: Process completed with exit code 1.

Most likely cause

You’re using a custom personal access token (custom_github_token input) that is either:

• missing required permissions,
• passed incorrectly from your secrets,
• expired or has been revoked

How to fix

• Make sure your PAT is configured with read and write access to: Contents and Pull requests within your repo.
  • For fine-grained tokens, these are separate resources in the repo permissions UI. For classic tokens, this usually means the repo scope.
• Store the token in your repo or org secrets, and pass it like this:

custom_github_token: ${{ secrets.PAT }}

• Double-check that:
  • The PAT belongs to a user that has access to the target repo.
  • The PAT is not expired or revoked.
  • You didn’t accidentally paste extra spaces or quotes into the secret value.