Setup
Translations Setup
Setting up the translations management tool
Overview
The translations tool lives in the Admin app (apps/admin) under the Translations section. It reads JSON locale files from the monorepo via the GitHub API, provides a browser-based editor, and saves changes back as pull requests through a GitHub App.
Prerequisites
- Node.js 24+
- pnpm 10+
- A GitHub App installed on the repository (for branch/PR creation)
- Clerk account (for authentication — email must be in the admin allowlist)
Environment Variables
Create apps/admin/.env.local from the example:
cp apps/admin/.env.example apps/admin/.env.localAuth
| Variable | Required | Default | Description |
|---|---|---|---|
CLERK_SECRET_KEY | Yes | — | Clerk backend secret key |
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | Yes | — | Clerk publishable key |
GitHub App
| Variable | Required | Default | Description |
|---|---|---|---|
GITHUB_OWNER | Yes | — | Repository owner (org or user) |
GITHUB_REPO | Yes | — | Repository name |
GITHUB_BASE_BRANCH | Yes | — | Base branch for translation PRs (e.g. main) |
GITHUB_APP_ID | Yes | — | GitHub App ID |
GITHUB_APP_INSTALLATION_ID | Yes | — | GitHub App installation ID |
GITHUB_APP_PRIVATE_KEY | Yes | — | GitHub App private key (PEM format) |
Translations
| Variable | Required | Default | Description |
|---|---|---|---|
TRANSLATIONS_PACKAGE_PATH | Yes | — | Path to translations package relative to repo root (e.g. packages/i18n-messages) |
TRANSLATIONS_SOURCE_PATH | Yes | — | Path to locale files relative to the translations package (e.g. src/locales) |
TRANSLATIONS_SUPPORTED_LOCALES | No | (all found) | Comma-separated list of supported locales (e.g. en,fr) |
TRANSLATIONS_BRANCH_PREFIX | No | translations | Branch name prefix for translation PRs |
GitHub App setup
The app authenticates as a GitHub App installation (not a personal token). You need:
- Create a GitHub App with Contents (read & write) and Pull requests (read & write) permissions
- Install it on the target repository
- Copy the App ID, Installation ID, and generate a private key
- Set the three
GITHUB_APP_*env vars
Running
# Start the admin app (Turbo + Next.js Turbopack)
pnpm dev:admin
# Or from the app directory
cd apps/admin && pnpm devThe app runs on http://localhost:3006; the translations tool is at /translations/namespaces.
Access control
Access is gated by the account role stored in the database: the translations tool needs translator (or admin, which satisfies every role). Other users are redirected to /unauthorized.