hyperlocalise

Hyperlocalise is AI-native localization infrastructure for modern apps.

It combines a local-first CLI, CI automation, and storage adapters so localization workflows can live inside your engineering system instead of beside it.

Docs

The full product documentation lives at hyperlocalise.dev.

• Cloud: Platform overview
• CLI getting started: Install, Quickstart, First project
• Configuration: i18n config, provider credentials
• Commands: CLI overview, run, eval, status, sync pull, sync push
• Workflows: local generation, CI automation, TMS curation loop
• Providers: provider overview
• TMS adapters: storage overview

Install

Install the latest stable CLI:

curl -fsSL https://hyperlocalise.com/install | bash

Pin a specific release:

curl -fsSL https://hyperlocalise.com/install | VERSION=v1.2.3 bash

Install the Hyperlocalise skill from this repository:

npx skills add . --skill hyperlocalise

Install it directly from GitHub:

npx skills add https://github.com/hyperlocalise/hyperlocalise --skill hyperlocalise

CLI overview

The CLI centers on four workflows:

• run: generate local translations and write target files
• eval: score and compare translation quality
• sync: pull from or push to supported storage adapters
• status: report translation coverage and review state

Other commands include init, completion, update, and version.

For review-time validation, check also supports --diff-stdin to scope findings to changed keys from a unified patch for configured .json, .jsonc, and .arb translation files.

Local generation supports common app resource formats including JSON/JSONC, ARB, XLIFF, PO, Qt Linguist .ts, HTML, Liquid, Markdown/MDX, AsciiDoc, Apple .strings/.stringsdict, CSV, and Android res/values*/strings.xml resource files.

Use hyperlocalise --help for the local command surface, or see the docs for full flags, examples, and provider-specific setup.

GitHub Action

This repository ships two composite GitHub Actions:

• action.yml: opinionated localization CI checks (drift and check)
• install/action.yml: install the Hyperlocalise CLI from GitHub releases

Install the CLI in a workflow:

- uses: hyperlocalise/hyperlocalise/install@v1
  with:
    version: latest

Use @v1 for the latest compatible release, or pin an exact tag such as @v1.3.1 for stricter control.

Hyperlocalise CI

The root action at action.yml runs localization checks in CI.

Current scope:

• Action name: Hyperlocalise CI
• Supported checks in v1: drift and check
• drift runs hyperlocalise run --dry-run and reports planned localization changes
• check runs hyperlocalise check --format json and reports localization integrity findings
• check can pass the GitHub pull request diff to hyperlocalise check --diff-stdin so annotations focus on changed translation keys

This repository publishes a moving major ref for stable v1 releases. Use @v1 for the latest compatible action, or pin an exact tag such as @v1.3.1 for stricter control.

Example: check mode with annotations and artifact upload

jobs:
  localization-check:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
    steps:
      - uses: actions/checkout@v4

      - uses: hyperlocalise/hyperlocalise@v1
        with:
          check: check
          config-path: i18n.yml
          hyperlocalise-version: latest
          fail-on-findings: true
          github-diff: true
          upload-artifact: true

Example: drift mode in reporting-only mode

jobs:
  localization-drift:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4

      - uses: hyperlocalise/hyperlocalise@v1
        with:
          check: drift
          config-path: i18n.yml
          hyperlocalise-version: latest
          fail-on-drift: false
          upload-artifact: true

SQS Lambda workers

Use the create-sqs-lambda-worker skill in .agents/skills/ when adding a Go-first SQS-triggered Lambda. It scaffolds the handler contract, partial batch failure tests, shared Secrets Manager metadata, build target, and deployment handoff. The infrastructure repository provides the matching add-sqs-lambda-worker skill and reusable OpenTofu module.

The standard deployment action is .github/actions/deploy-lambda-artifact. It builds a root-level bootstrap, uploads a versioned S3 artifact, and updates the function named by SSM. Secret values stay in Secrets Manager; Lambda receives only ARN, JSON-key, and cache metadata through environment variables.

All Postgres-backed SQS Lambdas (activity-log, glossary-interchange, memory-interchange, visual-context-match) use the same database secret metadata and Go bootstrap:

• DATABASE_URL_SECRET_ARN, DATABASE_SECRET_KEY, and optionally DATABASE_URL_SECRET_CACHE_TTL_SECONDS
• secretsmanager.ConfigFromEnv() plus NewLoader in main

Infrastructure passes those variables either through the activity-log wrapper module or through secret_references.database_url_secret on sqs-lambda-consumer, with an explicit DATABASE_SECRET_KEY = "DATABASE_URL" in environment_variables (required because ConfigFromEnv() reads DATABASE_SECRET_KEY, not DATABASE_URL_SECRET_KEY).

Workers that need additional Secrets Manager fields beyond Postgres should use generic <NAME>_ARN, <NAME>_KEY, and <NAME>_CACHE_TTL_SECONDS from infra secret_references with ConfigsFromEnv("NAME", ...) and Collection. See .agents/skills/create-sqs-lambda-worker/references/worker-contract.md.

The translation-memory interchange worker uses the dedicated MEMORY_INTERCHANGE_QUEUE_URL producer variable and publishes versioned {schemaVersion, attemptId, operation} messages. Its artifact is memory-interchange/bootstrap.zip, built by make build-memory-interchange-lambda, and its Lambda function handoff is /hyperlocalise/prod/lambda/memory-interchange/function_name. Imports upload to the memory-interchange/ object prefix, support an asynchronous preview and apply, and exports become downloadable after the worker records a completed run. The infrastructure queue must be provisioned before enabling the publisher; deploy the real artifact before redriving placeholder or DLQ messages.

The visual-context match worker binds native strings to CAT screenshots with OCR, modelled on Smartling's context match processes. go-svc publishes {schemaVersion, processId} messages when VISUAL_CONTEXT_MATCH_QUEUE_URL is set; without it the match API returns visual_context_matching_unavailable. Its artifact is visual-context-match/bootstrap.zip, built by make build-visual-context-match-lambda, and its function handoff is /hyperlocalise/prod/lambda/visual-context-match/function_name. Besides the database secret variables, the Lambda reads OBJECT_STORAGE_S3_FILES_BUCKET, OBJECT_STORAGE_S3_FILES_REGION, optional OBJECT_STORAGE_S3_FILES_ENDPOINT, OBJECT_STORAGE_DEFAULT_LOCATION, and optional TEXTRACT_REGION. Its role needs s3:GetObject on the files bucket and textract:DetectDocumentText. Use a function timeout of at least 3 minutes and a queue visibility timeout above it.

GitHub Action settings

Inputs from action.yml:

• check: check name. Supported values: drift, check. Default: drift
• config-path: path to the i18n config file. Default: i18n.yml
• working-directory: working directory for the check. Default: .
• hyperlocalise-version: CLI version to install. Default: latest
• fail-on-drift: fail the action when drift is detected. Default: true
• fail-on-findings: fail the action when check findings are detected. Default: true
• upload-artifact: upload the JSON report and text summary. Default: true
• github-annotations: emit inline GitHub workflow annotations for check findings. Default: true
• github-diff: in check mode on pull requests, fetch the GitHub PR diff and pass it to hyperlocalise check --diff-stdin. Default: false

Outputs:

• drift-detected: true, false, or unknown
• findings-detected: true, false, or unknown
• cli-exit-code: exit code returned by the Hyperlocalise CLI
• report-path: path to the generated JSON report
• summary-path: path to the generated text summary
• findings-total: total number of reported errors and warnings
• error-count: number of error-level findings
• warning-count: number of warning-level findings

Operational notes:

• In drift mode, the action runs hyperlocalise run --dry-run --output <report-path>.
• In check mode, the action runs hyperlocalise check --no-fail --json-report <report-path> and then applies fail-on-findings in the action.
• When github-diff is true, check mode runs with --diff-stdin; this checks changed keys only for supported .json, .jsonc, and .arb translation files and uses those findings for annotations.
• If the CLI fails before completing a clean report run, the action fails.
• If the report state cannot be determined, the action fails.
• When upload-artifact is enabled, the action uploads both the JSON report and the text summary.
• When fail-on-drift is false, the action can be used in reporting-only mode.
• When fail-on-findings is false, the check mode can be used in reporting-only mode.
• When GitHub step summaries are available, the action writes counts such as Errors: 3 and Warnings: 5 to the run summary.
• In check mode, the action can emit inline GitHub annotations when the report includes file and line metadata.
• GitHub workflow-command annotations are capped at the first 50 findings per run.

Supported integrations

LLM providers are documented in the docs site and currently include openai, azure_openai, anthropic, lmstudio, groq, mistral, ollama, gemini, bedrock, openrouter, and ai_gateway.

Storage adapters are documented in the docs site and in internal/i18n/storage/, with support for crowdin, lilt, lokalise, phrase, poeditor, and smartling.

Development

Useful repo paths:

• apps/cli/: CLI application entrypoint
• apps/cli/cmd/: CLI command handlers
• apps/hyperlocalise-web/: web app workspace
• apps/figma-plugin/: Figma design editor plugin
• apps/canva-app/: Canva design editor app
• internal/: shared internal packages
• pkg/platform/: runtime, auth, transport, and observability helpers
• scripts/: project scripts

Common commands:

make bootstrap
make fmt
make lint
make test-workspace
make check-build

For contributor guidance, see docs/contributing/development.mdx.

Release

Create and push a semantic version tag to trigger release CI:

git tag v0.1.0
git push origin v0.1.0

Release assets are built by GoReleaser via .github/workflows/release.yml and .goreleaser.yml.

License

The CLI, shared Go packages, GitHub Actions, and repository files are licensed under the MIT License unless a more specific license file applies.

The web application in apps/hyperlocalise-web/ and the Canva app in apps/canva-app/ are licensed separately under the Business Source License 1.1 by Hyperlocalise Pty Ltd. See each directory's LICENSE file for the Licensed Work definition, Additional Use Grant, Change Date, and Change License. Hyperlocalise-owned source files in those trees carry a BSL header; third-party files retain their own notices. Use node scripts/add-bsl-headers.mjs when adding new files.

The Figma plugin in apps/figma-plugin/ is also licensed separately under the Business Source License 1.1. See apps/figma-plugin/LICENSE.

Contributing

Issues and pull requests are welcome.