CurseForge Localizations

A small script to manage localization strings for World of Warcraft AddOns when using CurseForge's localization feature.

It will (recursively) scan Lua files for text matching the AceLocale format (e.g. L["An example"]), then upload them to CurseForge. In essence it'll keep the strings used in the project code in-sync with CurseForge. It's a perfect companion to localization substitution in packagers.

Using AceLocale in your project is not required, the structure it defines has become the default that many libraries/addons use, and AceLocale is the most common way to use it.

The script uses the CurseForge Upload API, which requires authentication (see below).

Usage

usage: update.py [-k KEY] [-i ID] [-l OPT] [-m OPT] [-n OPT] [-e OPT] [-p OPT] [-d] [-h]

required arguments::
  -k, --key KEY        API key or path to file that contains the key for CurseForge,
                       can also be defined as CF_API_KEY environment variable
  -i, --id ID          project ID on CurseForge

optional arguments::
  -l, --lang OPT       base language of strings (default = enUS)
  -m, --missing OPT    how to handle missing phrases (default = DoNothing)
  -n, --namespace OPT  namespace to upload to
  -e, --exclude OPT    pattern of files and/or directories to ignore
  -p, --pattern OPT    regex pattern used to find strings
  -d, --dry            dry-run, print strings instead of uploading
  -h, --help           show this help message

For the tool to work correctly (i.e. upload strings) it needs at minimum two pieces of information:

• it needs the API key to talk to the CurseForge API
  • you can generate one here: https://authors-old.curseforge.com/account/api-tokens
  • the script can read this from a file, an environment variable, or as a plain string argument
• it needs the project ID on CurseForge
  • see the right column of your project's webpage on CurseForge
  • if this is not provided as an argument the script will attempt to find it from the X-Curse-Project-ID field in nearby TOC files, as it's commonly used/defined that was by other tools

And you obviously need to enable the Localization feature on CurseForge for your project;

https://legacy.curseforge.com/wow/addons/YOUR_PROJECT/settings/general

The additional options should be pretty straight-forward, although some are quite advanced.
Please refer to the CurseForge support article for some of them.

If you have any questions on how to use the script, feel free to open a discussion.

Example workflow

The script can be used as an action in a GitHub workflow;

name: Upload localization strings to CurseForge

on:
  push:
    branches:
      - master
    tags-ignore:
      - '**'

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - name: Clone project
        uses: actions/checkout@v4

      - name: Upload localizations
        uses: p3lim/curseforge-localizations@v1
        with:
          handle_missing: DeletePhrase # optional
          exclude: | # optional
            libs/*
            testing.lua
        env:
          CF_API_KEY: ${{ secrets.CF_API_KEY }}