Exports the translations of a Tolgee project into flat JSON files and checks that nothing is missing in the language your users fall back to.
The plugin does one thing: it brings translations into your repository. It never writes to Tolgee, it ships no runtime library, and it never hooks itself into your build lifecycle uninvited.
- Plugin id:
one.epicsoft.tolgee - License: MIT
- Source: developed on GitLab, mirrored to GitHub — issues are welcome on both; code changes only as merge requests on GitLab, the mirror cannot take pull requests
Usage
1. Apply and configure
The plugin is on the Gradle Plugin Portal, which Gradle asks by default — there is no repository to declare.
// build.gradle
plugins {
id "one.epicsoft.tolgee" version "1.1.3"
}
tolgee {
url = "https://tolgee.example.com"
projectId = 16
tag = "core"
languages = ["en", "de"]
outputDir = layout.projectDirectory.dir("src/main/resources/messages")
referenceLanguage = "en"
}2. Run
./gradlew pullTranslations # download <language>.json into outputDir
./gradlew verifyTranslations # check the fallback language, no networkConfiguration
| Option | Type | Default | Description |
|---|---|---|---|
url | String | — | Required. Base URL of the Tolgee instance. |
projectId | Int | — | Required. Numeric project id. |
languages | List<String> | — | Required. Language codes to export. |
outputDir | Directory | — | Required. Where <language>.json is written. |
tag | String | — | Export only keys carrying this tag. Without it the whole project is exported. |
apiKeyEnv | String | TOLGEE_API_KEY | Name of the environment variable holding the API token. |
referenceLanguage | String | — | Master language: every other language in languages needs a value for every key it has a value for. Must be one of languages. |
fallbackLanguage | String | — | Language that needs a value for every key found in any language; must be one of languages. Without it and without referenceLanguage, verifyTranslations does nothing. |
failOnMissingToken | Boolean | false | true makes a missing token fail the build instead of skipping the download. |
The token is never part of the configuration — only the name of the environment variable it comes from. A field that accepts a token eventually contains one, and then it lives in a build file inside a repository. For the same reason the token is not declared as a task input: that would write it into the configuration cache and the build cache key.
Tasks
pullTranslations
Downloads one file per language, in parallel, and writes them as flat JSON sorted by key.
- Without a token it logs one line and leaves the committed files untouched, so everyone can build the project. Set
failOnMissingToken = truein the job that is supposed to refresh them. - All or nothing: every language is fetched before the first file is written. A half updated set of files is worse than a set that is one day old.
- Never an empty file: an empty, nested or unparsable response fails the task and leaves what is on disk alone. An empty translation file does not look broken — it looks like a product without labels.
- Files are replaced atomically, so an interrupted run cannot truncate one.
- Plain HTTP warns: a
urlwithhttp://to anything but loopback logs a warning, because the token would travel unencrypted. It does not fail — whether that is acceptable is the consumer’s call. - The task always runs when invoked; the remote content changes without any local input changing, so an “up-to-date” verdict would be a lie.
verifyTranslations
Reads the committed files, no network access. Two checks, each switched on by its own setting:
referenceLanguage— the language texts are written in. Every other configured language needs a value for every key the reference has a value for; the failure lists the gaps per language. Extra keys in another language are fine, and a key without a text in the reference is not one of its keys.fallbackLanguage— the language a reader falls back to. It needs a value for every key found in any configured language, so a key missing from the fallback file entirely is caught as well as one that is present but empty.
Asking for both tasks in one invocation works: verification is ordered after the download (mustRunAfter, not dependsOn), so the two never race, and verifying alone still never touches the network.
Notes
Sorted keys. The export order is the server’s business and can change between calls. Sorting turns a single changed string into a single line diff instead of a rewritten file.
Flat JSON. The export request sends an empty structureDelimiter parameter. Without it Tolgee nests the result on every . in a key, and a consumer that expects flat keys — ngx-translate, a JSON backed Spring MessageSource — finds nothing: the build stays green and only the user interface is empty. The plugin rejects a nested response rather than writing it.
HTML characters such as <, > and & are written as they are. Escaped translation files are unreadable in review and needlessly different from what Tolgee returned.
Lifecycle. Nothing is wired into assemble or build. If you want that, say so yourself:
assemble.dependsOn pullTranslationsDevelopment
./gradlew build # compile, validate the plugin, run the tests
./gradlew test # tests only
./gradlew publishPlugins --validate-only # checks the Plugin Portal metadata, uploads nothingOn main the pipeline also checks the runtime dependencies — Gson and the Kotlin standard library, the JARs the plugin brings into your build: their licenses (./gradlew checkLicense, permissive licenses only), known vulnerabilities (OWASP dependency-check) and newer versions. It also builds with deprecated Gradle features treated as errors, so they show up before the next Gradle major removes them. It runs on every push and weekly.
Requires a Gradle daemon on Java 25. Consuming projects may target any Java version.
Built with Gradle 9.8.2 and the Kotlin JVM plugin 2.4.21, tested with JUnit 6. The two need not be identical — Gradle 9.8.2 embeds Kotlin 2.4.10 — because this project compiles plain Kotlin sources rather than precompiled script plugins, where the embedded version does have to match. Keep an eye on it when raising the wrapper: a genuine incompatibility shows up as incompatible version of Kotlin at compile time.
Layout
src/main/kotlin/one/epicsoft/gradle/tolgee/
├── TolgeePlugin.kt # entry point — registers extension and tasks
├── TolgeeExtension.kt # the tolgee { } block
├── api/
│ ├── ExportUrl.kt # builds the export URL
│ └── TranslationJson.kt # parsing and writing the flat JSON
└── task/
├── PullTranslationsTask.kt
└── VerifyTranslationsTask.ktReleasing
- Raise
versioningradle.properties - Update the version in this README (plugin block above)
- Head the
CHANGELOG.mdentry with## [X.Y.Z] - <date>of the coming release — never[Unreleased], never a bare date - Tag that commit on
mainwithX.Y.Z— no leadingv— and push the tag; the CI publishes that version to the GitLab package registry and the Gradle Plugin Portal and creates the GitHub release with theCHANGELOG.mdentry and the JARs
Work happens on main, and every tag sits there. Publishing to the Portal needs the CI variables GRADLE_PUBLISH_KEY and GRADLE_PUBLISH_SECRET (masked, protected); a version there cannot be replaced, and a new plugin id waits for a manual review.
Optional package mirror
The build resolves from the Gradle Plugin Portal and Maven Central. To route it through a mirror, set GRADLE_PLUGIN_MIRROR_URL and/or MAVEN_MIRROR_URL in the environment, optionally with MAVEN_MIRROR_USERNAME and MAVEN_MIRROR_PASSWORD. Nothing about a mirror is stored in this repository.
License
The MIT license applies only to files created by epicsoft LLC. Third-party files, such as the Gradle wrapper, remain under their own licenses.