DEV Community: Arvid Andersson

Should Translations Go in the Same PR or a Separate One?

Arvid Andersson — Fri, 21 Aug 2026 11:40:46 +0000

If you ask an AI assistant how to automate i18n in CI, it will most often recommend a separate translation PR. The reasoning goes: a separate PR is cleaner, reviewers can tell source-code changes apart from localization churn and slow human translations don't block feature development.

That's a real argument, but from watching how teams actually work with translations we've landed somewhere else: most times translations belong in the pull request that introduced the strings. Kundo moved nine languages off an agency and a TMS to automated translations on every pull request. A glossary and style guide keep the output on-brand by default, so most of it just flows and the team steps in on the strings that warrant a second look.

The case for a separate PR

The diff stays readable. If your feature PR touches eight files and the bot adds translations for nine languages, your diff goes from eight files to seventeen. A reviewer scrolling for the actual logic change has to skip past a lot of YAML.

Translations can't block the feature. If translation takes hours, or a human has to review the Japanese, the feature waits. A separate PR decouples them: ship the feature now, merge translations when they're ready.

A clear gate. Some teams genuinely want an explicit approval step for anything customer-facing owned by someone who isn't the developer.

Those are the reasons you usually get. If you take nothing else from this post: if your translations involve slow human turnaround and you have no way to review them outside a code diff, a separate PR is the right call. That was the world most of this advice was written in.

Why we do it the other way

A feature isn't done until it's translated. This is the core of it. If your feature merges to main in English and the translations arrive in a PR two days later, then for two days main contains a half-finished feature. Anyone deploying in that window ships English strings to Japanese users. The "separate PR doesn't block the feature" argument is really "separate PR lets you merge something incomplete", which is only an advantage if you think of translations as an afterthought rather than part of the work.

Review happens where the reviewer is. The diff-churn objection assumes translations get reviewed in the diff. That's the part we'd push back on: a YAML diff is a bad place to review copy. Your PM doesn't read it. Your native Japanese speaker on the support team doesn't have a GitHub account. Move that review into a dashboard, where someone sees the source string next to the suggestion and can fix it before merge and the diff never needs to be the review surface at all. The churn objection dissolves, because nobody was reading that part of the diff anyway.

Git history stays clean. Separate translation PRs pile up. They go stale when the feature branch changes. They get merged out of order. They occasionally conflict with each other. Ship weekly for six months and that's twenty-odd "chore: translations" merges interleaved with the real work and bisecting through it is worse not better.

One unit of work. The feature, its strings and its translations are one change. Reviewing them together is how you catch that the new button label doesn't fit in German before it reaches production, rather than after.

Consistency is the actual bar, not coverage. Translations are good when they sound like your product: same formality throughout, same term for the same concept every time, "Dashboard" not "Übersicht" in one screen and "Dashboard" in the next. Getting the strings into the repo is the easy half. That's what a style guide and glossary are for. Keeping it in the same PR is what makes them easy to enforce: the person who wrote the string is right there, still holding the context and can see the German before it merges. Fix a bad term then and it costs a comment. Fix it after three more features have copied the wording and it costs an afternoon.

Where should translations be reviewed?

The tradeoff turns on one question: do you have a review surface outside the diff?

If you don't, the separate-PR advice can be sound and the AI assistants recommending it aren't wrong. Without somewhere to review translations they either land in your diff unreviewed or they block your merge.

If you do, the calculus flips. Translations stop being noise in the code review and become their own reviewable thing, handled by whoever should be handling them. The feature and its translations ship as one unit. Your diff has more lines in it and nobody minds, because nobody is reading them line by line.

That's the design choice behind how Localhero.ai works. The GitHub Action picks up only the keys that are new or changed, translates them against your glossary and style guide, runs quality checks on the result and commits it into the pull request that introduced the strings. That takes seconds and it happens before anyone looks at the PR.

Then, if someone wants to check a string, the review happens in a dashboard: the source string, the suggestion, the glossary term it should have used and an edit box. Edits sync back to the same pull request as a commit before it merges. No GitHub account needed, no code diff to read, and no separate PR to chase. This isn't a sign-off on every string, either. Once a glossary and style guide are in place the output is consistent by default, so review is something you reach for on the copy that matters, not a gate everything has to clear.

That ordering is deliberate. The same-PR model only holds up if reviewing outside the diff is genuinely good, which is why most of our product work goes there rather than into the translation step. Translation quality is largely a solved problem now, given the right glossary, context and checks. Making the output reviewable by the person who owns the words is the part still worth building.

When a separate PR can be the better call

Three cases, and the first one is a cost rather than a reason to switch.

Your diff really is bigger. This isn't free. If your team reviews PRs by reading every changed line top to bottom, you'll feel it. Most reviewers collapse or filter locale files when they hit a big PR, which handles it, but it's a real change to the review experience.

If translations are slow, this hurts. The model depends on translations arriving in seconds, not days, which is the whole reason automating that step matters. If a human has to produce the first draft, the feature genuinely waits, and the fix is usually to flip the order: let the machine write the first pass so the merge isn't blocked, and keep the human on the strings worth their attention.

Some teams might need a gate. Regulated industries, legal copy, brand-critical marketing strings. If a lawyer or a compliance officer has to sign off before customer-facing text merges, and the sign-off needs its own audit trail separate from code review, a separate PR is the better answer and we would tell you the same thing. Same if the translations are owned by an outside vendor on their own schedule. The argument in this post is about product UI strings that your own team owns, not every string in every company.

Same PR or separate for translations: how to decide

The advice to use a separate PR made sense when translation meant sending a spreadsheet to an agency and waiting. Most of the tooling and most of the advice written about the tooling still assumes that world.

If translations arrive in seconds and can be reviewed somewhere a non-developer can work, keeping them in the same PR is simpler: one unit of work, one review, one merge, and main is never half shipped.

The PR question is a real one and your team will have opinions about it, so it's worth working through rather than inheriting a default. The part we'd start from is review. If someone needs to read the generated strings before they ship, and usually someone does in some form, work out who that person is and where they'd do it. The PR shape mostly follows from that answer.

How to Automate i18n Translations with GitHub Actions: 3 Approaches

Arvid Andersson — Fri, 21 Aug 2026 08:05:17 +0000

TLDR: You can automate translations by triggering AI translations on every pull request with GitHub Actions. No more waiting on translations before shipping. This post walks through different approaches that work with your React, Rails, Next.js, and Django projects.

I've seen the same pattern at almost every team that ships a product in multiple languages. The feature is built, tests pass, the PR is ready to merge, but translations aren't done. Either the release gets delayed or it goes out with missing strings in half the languages.

The root cause, in my experience, is that translations live outside the development workflow, even in projects where the translation files are checked into the codebase. They end up being managed through spreadsheets, Slack channels or external platforms that aren't connected to your git flow. Every new feature requires someone to manually coordinate getting the translations done. And that someone is usually a developer who has better things to do.

The fix is straightforward: make translations part of your CI/CD pipeline. When a developer pushes code with new translation keys, translations should be generated automatically, just like tests run automatically.

Why GitHub Actions for translations?

GitHub Actions is the natural place to automate translations because it's already where your code lives. Instead of syncing files back and forth between your repo and an external platform like Lokalise or Phrase, translations happen right in the pull request workflow.

Here's what an automated translation workflow looks like:

You add new translation keys in the source language
A pull request is opened for the changes
GitHub Action detects new or changed keys
Translations are generated (via API call to a translation service)
Translated files are committed back to the branch
Reviewer sees both code changes and translations in the same PR

This means translations are always part of the code review process, always version-controlled, and always ready to ship with the feature. No waiting for someone to get back to you.

For most teams, auto-commit to the PR branch plus a staging review works well. Translations land automatically, and your team catches issues in context before production. For marketing copy or anything brand-sensitive, you might want an explicit approval step before merging.

Approach 1: DIY with a LLM API

If you want full control, you can build a simple GitHub Action that calls the OpenAI API (or any LLM API) directly to translate your i18n files.
It's a quick approach for smaller projects where you don't need to ensure brand voice consistency and similar. It can work well for getting started.

Here's a minimal example for a project using JSON translation files:

The translation script

// scripts/translate.js
const fs = require('fs');
const path = require('path');

const SOURCE_LOCALE = 'en';
const TARGET_LOCALES = ['sv', 'de', 'fr', 'es'];
const LOCALES_DIR = './locales';

async function translateWithOpenAI(texts, targetLang, apiKey) {
  const response = await fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      model: 'gpt-4o',
      messages: [
        {
          role: 'system',
          content: `You are a professional translator. Translate the following JSON values from English to ${targetLang}. Keep the JSON keys unchanged. Only return valid JSON, no explanation.`
        },
        {
          role: 'user',
          content: JSON.stringify(texts)
        }
      ],
      temperature: 0.3
    })
  });

  const data = await response.json();
  return JSON.parse(data.choices[0].message.content);
}

async function main() {
  const apiKey = process.env.OPENAI_API_KEY;
  const sourceFile = path.join(LOCALES_DIR, `${SOURCE_LOCALE}.json`);
  const sourceTexts = JSON.parse(fs.readFileSync(sourceFile, 'utf8'));

  for (const locale of TARGET_LOCALES) {
    const targetFile = path.join(LOCALES_DIR, `${locale}.json`);
    const existing = fs.existsSync(targetFile)
      ? JSON.parse(fs.readFileSync(targetFile, 'utf8'))
      : {};

    const missing = {};
    for (const [key, value] of Object.entries(sourceTexts)) {
      if (!existing[key]) {
        missing[key] = value;
      }
    }

    if (Object.keys(missing).length === 0) {
      console.log(`${locale}: all keys present, skipping`);
      continue;
    }

    console.log(`${locale}: translating ${Object.keys(missing).length} keys...`);
    const translated = await translateWithOpenAI(missing, locale, apiKey);
    const merged = { ...existing, ...translated };

    fs.writeFileSync(targetFile, JSON.stringify(merged, null, 2) + '\n');
    console.log(`${locale}: done`);
  }
}

main().catch(console.error);

The GitHub Action workflow

# .github/workflows/translate.yml
name: Auto-translate i18n
on:
  pull_request:
    paths:
      - 'locales/en.json'

jobs:
  translate:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Translate missing keys
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: node scripts/translate.js

      - name: Commit translations
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add locales/
          git diff --cached --quiet || git commit -m "Auto-translate: update i18n files"
          git push

Pros: Full control, no external dependencies, cheap (just OpenAI API costs).

Cons: No brand voice management, no glossary support, no quality controls, no context awareness, no UI for managing translations, and you have to maintain the script and prompts yourself. For a side project, that's fine. For a production app with 10 languages, it gets old fast.

Framework-specific setup notes

Whatever your stack, the paths: trigger in the workflow file just needs to point at your translation files:

React (react-i18next): public/locales/{lang}/translation.json or src/locales/{lang}.json
Next.js (next-intl or next-i18next): messages/{lang}.json or public/locales/{lang}/
Ruby on Rails (Rails I18n): config/locales/{lang}.yml (you'll need a YAML parser that handles nested keys and pluralization)
Django (gettext): locale/{lang}/LC_MESSAGES/*.po (more involved, you need to extract messages with makemessages first to know which keys were added, then parse and generate PO files)

Approach 2: Using a translation management tool

The DIY approach works for simple projects, but it starts to break down when you need consistent terminology, brand voice, or you're dealing with complex file formats (nested YAML, pluralization rules, ICU messages). This is where dedicated translation tools come in.

The established players in this space, Lokalise, Phrase, Crowdin, and Transifex, were built when translations meant coordinating human translators. They're basically project management tools for localization: you sync files to their platform, assign work to translators, manage review workflows, and sync the finished translations back. That model makes sense if you have a dedicated localization team and professional translators. But for modern product teams where dev teams drive the workflow, it's a lot of infrastructure for a problem that doesn't need to be that complicated. (We cover how to choose between these approaches in a separate post.)

Tools like Localhero.ai (disclosure: I built this) take a different approach: automate as much as possible with AI, and build nice tooling for the rest. A CLI plugs directly into your GitHub Actions workflow so translations happen in the PR automatically, and a web-based UI gives you glossary management, style guides, quality checks, and a review interface for when you need to tweak things by hand.

Here's what the setup looks like using the Localhero.ai GitHub Action:

# .github/workflows/localhero-translate.yml
name: Translate with Localhero.ai

on:
  pull_request:
    paths:
      - 'locales/**'
      - 'localhero.json'

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: localheroai/localhero-action@v1
        with:
          api-key: ${{ secrets.LOCALHERO_API_KEY }}

The action handles fetching the base branch for comparison, translating missing keys, and committing changes back to the PR. It also skips automatically for draft PRs, bot commits and PRs with a skip-translations label.

The translations committed to the PR on GitHub

The same translations on Localhero.ai, where you can review and edit

The difference from the DIY approach is that the translation service maintains your style guides and glossaries, so "checkout" always gets translated consistently across every PR, and your brand voice stays consistent as your team grows. You also get a review view where you can review and edit translations, then push changes back to the PR without touching git. Handy when someone on the team who doesn't live in the terminal wants to tweak a translation before it ships.

Approach 3: Self-hosted open source

If you need to keep everything on your own infrastructure, maybe for data residency requirements, regulatory compliance or because your content is sensitive, self-hosting the translation platform is an option. This means running your own service that manages glossaries, style guides, and review workflows, while still plugging into GitHub Actions the same way as the other approaches.

You don't have to self-host the AI models too. Most self-hosted setups still call commercial LLM APIs (OpenAI, Anthropic, etc.) for the actual translations, you just control where the platform data lives. If even the API calls are a concern, tools like LibreTranslate let you run translation models fully locally, but the quality trade-off is real, especially for less common language pairs.

The main cost here is setup and maintenance. You're running infrastructure, keeping it updated, and building the tooling that managed services give you out of the box. I think this approach makes the most sense when data control is a hard requirement, not just a preference.

Choosing the right approach

This table compares the three approaches. If you're past that and comparing specific tools, we keep a separate comparison of the GitHub Actions and hosted tools that translate i18n files.

Factor	DIY (LLM API)	Dedicated tool	Self-hosted
Setup time	1-2 hours	5 minutes	2-4 hours
Translation quality	Good for simple text	Better (context + glossaries)	Depends on setup
Brand consistency	Manual effort	Built-in (style guides)	Depends on your tooling
Cost	LLM API costs (cents per PR)	From $29/month	Infrastructure + API costs
Maintenance	You maintain the script	Managed	You maintain everything
Best for	Side projects, MVPs	Production teams	Strict data requirements

Quick decision guide:

Must your data stay on your own infrastructure? → Self-hosted is your path. You can still use commercial LLM APIs for quality, but you'll own the platform setup and maintenance.
Is this a side project or MVP? → The DIY script works, but also check if your tool of choice has a free tier. Localhero.ai for example has a free plan with 250 credits (~4,000 words) per month, which covers most side projects.
Shipping a production app to multiple languages? → A dedicated translation tool saves you from maintaining translation scripts, keeps terminology consistent as you scale, and usually gives you a web UI where the whole team can review and edit translations.

Tips for better automated translations

Regardless of which approach you choose, these practices improve translation quality. I've found them to be consistently useful across different project sizes to ensure brand/quality consistency and developer happiness.

Use descriptive, hierarchical translation keys

Keys like btn.submit don't give the translator (human or AI) enough context. Use hierarchical keys that scope translations clearly. checkout.submit_order_button tells you exactly where in the app this string lives and what it does. A key like settings.notifications.email_digest_label is better than notif_email because the hierarchy provides context that the translator can use. This one change can noticeably improve translation quality, especially with AI translators that use the key name as a signal.

Only translate what changed

Focus your automation on keys that were added or modified in the current PR, not all missing keys across the project. The DIY script above does this by checking for missing keys. This keeps PRs focused and avoids churning translations that might be in progress elsewhere.

Review translations in staging

One benefit of PR-based translation workflows is that translations deploy to your staging environment along with the feature. You can see how translated text looks in the actual UI before merging, catching layout issues, text overflow, and awkward phrasing. In my experience, seeing the translation in context catches things that reviewing raw translation files never would. (For more on catching quality issues, see translation quality at scale.)

Maintain a glossary of product terms

Whether you manage it in a JSON file, a spreadsheet or a tool's glossary feature, having a single source of truth for how your product terms translate prevents inconsistencies like "workspace" being translated three different ways across your app. We have a separate post on setting up style guides and glossaries if you want to go deeper.

Don't block on perfection

AI translation quality with good context typically gets you 90-95% accuracy for product copy. Ship it, then iterate based on feedback. Your users care more about having features in their language than perfect phrasing in every edge case. For me, this was a mindset shift, but it's the right one.

For product UI strings, that's usually good enough on its own. Marketing pages or anything with cultural nuance can still benefit from a native speaker reviewing the output. The shift is that human review becomes an occasional quality check, not the bottleneck that blocks every release.

RAG Retrieval Architectures: When Better Embeddings Stop Helping

Arvid Andersson — Sun, 16 Aug 2026 18:02:59 +0000

Most RAG projects start vector-first: embed the documents, store them, retrieve by similarity. It works in the demo. Then a user searches for an exact thing, a product code, an error number, a specific name, and the system misses it, because vector search ranks by meaning, not by literal tokens. This post is about that failure and the retrieval architectures that fix it, as of June 2026.

The failure pure vector search hides

An embedding turns text into a point in a space where nearby points mean similar things. That is exactly what you want for "find documents about return policies" and exactly what you do not want for "find SKU-4471". The model encodes "SKU-4471" as something close to other codes that look and read like it, so the literal one a user typed can sit just outside the top results. The same happens with error codes, part numbers, ticket IDs, acronyms, and rare proper nouns.

This failure stays hidden through testing. Semantic queries work, the demo looks done, and then a user types the one exact thing they expected to match and loses trust in the whole system. It compounds in chat, where users phrase things literally and expect literal matches. A bigger or better embedding model does not fix it, because the problem is not embedding quality, it is that exact-match is a different job from semantic similarity.

A retrieval ladder, in order

Climb only as far as your evaluation says you need to. Each rung costs more.

Hybrid search. Run BM25 (keyword) and vector queries together, merge with rank fusion. Recovers exact tokens without losing semantic recall. The biggest single win for most projects.
Reranking. A cross-encoder re-scores the top candidates against the query and reorders them. Usually the next biggest quality jump after hybrid.
Query and metadata work. Query expansion, metadata filters, and better chunking. Helps when the right chunk exists but is not surfaced.
Structure-aware retrieval. Entity-aware retrieval or a graph layer (GraphRAG) for questions about entities, relationships, and identities that no single chunk answers.

Step 1: hybrid search

Hybrid search runs a lexical query (BM25 or full-text) and a vector query, then merges the two result sets, commonly with Reciprocal Rank Fusion. Lexical search nails exact terms and rare tokens; vector search nails paraphrase and meaning. The merge recovers what either alone would miss. This is the rung most projects should reach for first.

Reciprocal Rank Fusion is worth seeing in full, because it is simpler than it sounds. It ignores the raw scores from each system (which are not comparable anyway) and uses only the rank position:

def reciprocal_rank_fusion(result_lists, k=60):
    """Merge ranked ID lists. k dampens the weight of top positions."""
    scores = {}
    for results in result_lists:
        for rank, doc_id in enumerate(results):
            scores[doc_id] = scores.get(doc_id, 0) + 1 / (k + rank + 1)
    return sorted(scores, key=scores.get, reverse=True)

# bm25_hits and vector_hits are ranked lists of document IDs
merged = reciprocal_rank_fusion([bm25_hits, vector_hits])

That is the whole algorithm. A document ranked well by either system rises; a document ranked well by both rises further. Because it never compares a BM25 score to a cosine similarity, you avoid the score-normalisation problem entirely.

You can get hybrid two ways. A vector database with native hybrid support handles both signals in one query: Weaviate and Qdrant use BM25-based sparse plus dense vectors, and Pinecone pairs dense vectors with its own sparse model. Or you use a search engine built around hybrid from the start: Typesense and Meilisearch combine full-text and vector search with typo tolerance, and Azure AI Search offers full-text, vector, and hybrid in one managed service. The right choice depends on whether you already run a vector DB or want search-engine ergonomics (faceting, typo tolerance, geo) alongside retrieval.

Step 2: reranking

Hybrid search widens the net for recall, but the merged ranking is approximate. A reranker fixes the ordering: a cross-encoder reads the query and each candidate together and scores true relevance, then reorders. It is usually the highest-leverage quality change after hybrid, the lever to reach for once recall is good but precision lags.

Rerankers ship as hosted APIs alongside embeddings. Jina AI (part of Elastic since October 2025) offers a multilingual reranker next to its embeddings and reader; its reranker weights on Hugging Face are CC-BY-NC licensed, so commercial use goes through the API. Voyage AI (now part of MongoDB) provides rerank models with a free tier, focused on retrieval quality. Cohere offers a Rerank endpoint. The cost note that matters: rerank only the top candidates (often 50 to 100), not the whole result set, since a cross-encoder is far more expensive per document than a vector lookup.

Step 3: query and metadata work

If the right chunk exists but does not surface, the lever moves upstream. Query expansion generates variants of the incoming query (synonyms, expanded acronyms, alternate phrasings) and searches them in parallel, then merges, useful when users type terse or ambiguous queries. Metadata filters narrow the search space before retrieval (by date, source, language, or a field like country) which improves both precision and latency. And chunking strategy decides whether a relevant passage is even retrievable as a unit. These are worth tuning once hybrid and reranking are in place, not before.

Step 4: structure-aware retrieval

Some questions cannot be answered by ranking chunks at all. "Who is X" or "how is X related to Y" over a corpus where the answer is spread across many passages, with no single chunk acting as a summary, is a retrieval-structure problem. Entity-aware approaches build profiles or summaries per entity; GraphRAG-style approaches build a graph of entities and relationships and traverse it before or alongside chunk retrieval. RAG frameworks like LlamaIndex and Haystack provide building blocks for these patterns. This rung is real work and worth it only when evaluation shows ranking is not the bottleneck.

Build the eval set before you climb

The order above is a default, not a prescription. The way to know which rung you actually need is to build a small evaluation set first: a few dozen real queries with the documents that should answer them, then sort the failures into buckets, wrong documents retrieved, right document retrieved but answer missed it, query too vague. Each bucket points at a different rung. Adding features without measuring just moves the failure around. For the generation side of this (catching answers that cite the right chunks but draw the wrong conclusion), see the companion post on evaluating RAG quality beyond RAGAS.

Tools by step

Step	What it does	Tools
Hybrid (native)	Vector DB with built-in keyword + vector	Weaviate, Qdrant, Pinecone
Hybrid (search engine)	Full-text + vector search engine	Typesense, Meilisearch, Azure AI Search
Reranking	Cross-encoder re-scoring of candidates	Jina AI, Voyage AI, Cohere
Structure-aware	Entity and graph retrieval patterns	LlamaIndex, Haystack

Frequently asked questions

Why does my RAG system miss exact matches like SKUs or error codes?

Vector search ranks by semantic similarity, not literal token match. An embedding of "SKU-4471" or "error E-1042" lands near other codes that look similar in meaning, so the exact one a user typed can fall outside the top results. Embeddings are strong at meaning and weak at literal identifiers. The fix is hybrid search: run a keyword (BM25) query alongside the vector query and merge the results, so exact tokens are matched exactly while semantic recall is preserved.

What is hybrid search in RAG?

Hybrid search combines lexical search (BM25 or full-text) with vector search and merges the two result sets, usually with Reciprocal Rank Fusion. Lexical search catches exact terms, identifiers, and rare words; vector search catches paraphrases and semantic matches. Together they recover cases that either method alone would miss. Hybrid search is a common default in production RAG systems once they hit real queries.

Do I need a reranker if I already use hybrid search?

Often yes. Hybrid search widens the candidate set for recall, but the top of that merged list is not necessarily ordered by true relevance. A reranker (a cross-encoder model) re-scores the top candidates against the query and reorders them, which usually gives the largest precision gain after hybrid search. It adds latency and cost, so rerank a small candidate set (for example the top 50 to 100), not the whole index.

When should I move beyond hybrid search and reranking?

When evaluation shows the failures are no longer about ranking. If the right chunk is never retrieved regardless of method, the problem is upstream: chunking, metadata filters, or missing structure. Questions about entities, relationships, and identities across a corpus often need entity-aware retrieval or a graph layer (GraphRAG) rather than better embeddings. Build an eval set first so you change the layer that is actually failing.

Is hybrid search worth it for a small RAG project?

It depends on the documents. If your corpus contains identifiers, product names, codes, or rare technical terms that users search for literally, hybrid search pays off quickly. If the content is prose where meaning dominates and exact tokens rarely matter, pure vector search may be enough. The practical test is to build a small eval set with the queries you actually expect, then compare pure vector against hybrid on it.

Originally published on Infrabase.ai, where I maintain a hand-verified directory of AI infrastructure tools.

Translate i18n strings in CI with GitHub Actions: tools compared

Arvid Andersson — Sun, 14 Jun 2026 22:04:04 +0000

If your team ships a localized product continuously, translations have a way of becoming the step everything waits on. The feature is done, the PR is green, and then it sits because the German and Japanese copy is blank. The fix a lot of teams reach for is to move translation into CI: when a PR changes the source locale, something translates the new keys and commits them back before merge.

That loop, source PR in, localized product out, is the whole goal. The rest is which tool runs the middle step.

A quick summary of the options: the tools worth knowing for this are ai-i18n if you want open source and don't mind wiring it up; hosted actions like Lingo.dev for a quick CI hook; the big TMS platforms (Crowdin, Lokalise, Transifex) if you have a localization team; and Localhero.ai (ours), built around the translate-on-PR workflow with glossary consistency and a review UI for non-developers. What separates them isn't the API call. It's how consistent the output stays over time and whether a non-developer can review it.

One thing to keep in mind while you compare: getting an LLM to translate one string is easy. Getting consistent, on-brand translations across hundreds of keys and many languages, PR after PR, so "Workspace" is the same word in German every time and the tone doesn't drift, is not. And whatever you pick, someone usually still wants to review the copy that matters before it ships.

There are quite a few ways to run that step now, from open-source GitHub Actions you wire up yourself to hosted services that run as an Action. Before the tools themselves, here's what actually separates them.

What "good" looks like for CI translation

Most of these tools look similar in a demo. The differences show up a few months in, on a real product with real churn. The things that matter by then:

Delta translation. Translate only the keys that changed in the PR, not the whole file every time. It keeps CI fast and gives the model tighter context.
Glossary and tone consistency. "Workspace" should be translated the same way in PR #200 as it was in PR #5. It helps when a tool remembers the edits you've made and picks up the patterns already in your codebase, so corrections stick instead of getting re-litigated every PR.
A review surface. A YAML diff is not a place a PM or native speaker can sanity-check copy. Either you trust the output fully, or you need somewhere to review it.
Commit-back vs PR. Committing to the same PR is convenient; opening a separate translation PR is safer for some teams.

i18n translation tools that run as a GitHub Action

ai-i18n (open source GitHub Action). A solid choice if you want full control and don't mind wiring it up. It translates i18n files with an LLM provider you choose (Anthropic, OpenAI, or self-hosted Ollama), uses content hashing to translate only changed strings, and commits results back. It handles XLIFF and JSON (flat and nested). You own the config and the maintenance. Best when you want to tune everything yourself and keep the model choice in your hands.

Hosted CI-action tools (Lingo.dev and a few others). A handful of hosted services run their own GitHub Action that translates on the delta and commits back. Lingo.dev is one of the more visible ones. They cover the basic translate-in-CI loop across a range of CI providers. Where they differ from each other (and from the option below) is less the CI mechanics and more what happens around the strings: how consistent terminology stays over time, and whether a non-developer can review the output. Worth a look if you mainly want the CI hook itself.

Crowdin / Lokalise / Transifex (TMS with GitHub sync). The established translation management systems. They sync with GitHub (Crowdin opens a PR when translations update) and are built for teams with dedicated translators: assigning work, tracking who translated what, managing big translation projects. Crowdin has documented support for both react-i18next and LinguiJS. If you have a localization team and a lot of long-form content, this is the category for you. If you're a product team that just wants UI strings translated on every PR, it's usually more platform than the job needs.

Tolgee. Open source with a hosted tier, an in-context editor, and CI integration. Supports the major JS frameworks (React, Vue, Angular, Svelte, Next) plus JSON and PHP .po. Good middle ground if you want an open-source core plus a UI.

Localhero.ai (ours). Built for product teams that ship continuously. It runs as a GitHub Action, translates the changed i18n keys on each PR, and focuses on the two things that make this hold up on a real product: a glossary and brand voice that stay consistent across PRs via translation memory, and a review UI a PM or native speaker can use instead of reading a YAML diff. Works with react-i18next, LinguiJS, Rails (YAML), and Django (.po). We're also adding review for translations a PR already includes, not just the ones we generate, so teams bringing their own translations get the same review surface. It's narrower than a full platform on purpose. If you want a focused tool for the translate-on-PR workflow rather than a large platform to configure, it's worth a look. If you want to self-host or stay fully open source, ai-i18n or Tolgee fit better.

A rough decision guide

Want full control, open source, tune it yourself: ai-i18n or Tolgee.
Have a dedicated localization team and long-form content: Crowdin / Lokalise / Transifex.
A product team that ships continuously and wants UI strings translated per-PR, with glossary/brand-voice consistency and a review surface for non-devs: try Localhero.ai.

The pattern, regardless of tool

Whatever you pick, the setup that holds up is the same: translate only changed keys, protect placeholders before sending to the model, pass the glossary in context so terms don't drift, validate output before committing, and give someone a place to review brand-sensitive copy. The tool matters less than getting those pieces right.

The DIY route is genuinely viable, and we wrote up that pattern in detail here. The cost that's easy to undercount isn't the first build, it's the upkeep: the placeholder edge case that shows up six months later, the glossary logic, the model swap when prices change, the review surface someone eventually asks for. That work competes with your actual product for engineering time and attention. For some teams that ownership is worth it. For others, the reason to use a tool here is less the features and more not carrying that maintenance yourself.

Automating Translations With Your Coding Agent

Arvid Andersson — Wed, 08 Apr 2026 13:08:49 +0000

If you've been building features with Claude Code or Cursor, you know the feeling. You're in flow, the agent is writing components, wiring up routes, adding tests. Then you hit the translation strings. What's the German word for "workspace" that we should use? Is it "Arbeitsbereich" or did we decide to keep it as "Workspace"? Who should review this?

And even when you get the source strings right, the translations themselves are often a separate step. Someone coordinates them, someone else reviews them, the feature sits in a PR waiting. With AI coding agents speeding up development, this gap only gets wider.

Been working in this space for a while, and the thing that made the biggest difference was simple: just take the translation knowledge your team already has collectively, make it structured, and ensure your coding agent has access to it.

The problem isn't translating, it's consistency and brand voice

AI can translate. That's not the hard part any more. The hard part is getting translations that sound like your product, consistently, when multiple people and agents are all contributing to the same codebase.

Think about what happens without a shared glossary and style guide:

Developer A's agent translates "Workspace" as "Arbeitsbereich", Developer B's agent keeps it as "Workspace"
One PR uses formal German ("Sie"), another uses informal ("du")
A contractor pastes in ChatGPT translations with a completely different tone
Your native speaker on the team corrects the same term for the third time this month

The app ends up feeling like it was translated by five different people, because it was. Your brand voice gets lost the moment it crosses a language boundary. And every new language multiplies the problem.

This is why a glossary and style guide matter more than the translation engine. They're the single source of truth that keeps your brand voice consistent regardless of who or what writes the code.

Start with a glossary and style guide

Before you automate anything, sit down with and make some decisions. These are the things that no one, not your coding agent, not a new team member, not a translation tool, can figure out on their own easily:

Which terms should never be translated? Product names, feature names, technical terms your users know in English. "Workspace", "Dashboard", "API" might all stay as-is in German.
Which terms have a specific translation? Maybe "Save" is always "Speichern", not "Sichern". Maybe "team member" becomes "Teammitglied", not "Mitarbeiter". These are the terms your native speakers have opinions about.
What's the tone? Formal or informal? In German that's the difference between "Sie" and "du", in French between "vous" and "tu". This needs to be consistent across your whole app.
Any language-specific decisions? Scandinavian languages often sound better with a natural spoken register rather than formal written style. Japanese needs the right politeness level. These are things worth writing down once.

This is a conversation with your PM, your content person, the native speakers on your team. It doesn't take long, but the decisions need to be explicit, not just in someone's head. People usually have opinions and examples ready once you ask.

Once you have this in place, document it. Agents or tools that use it will produce translations that actually sound like your product. Without it, even the best AI will just guess differently every time.

A nice thing this opens up for is automating. The actual translations into target languages can then happen in CI. For example, a GitHub Action picks up new strings on the PR, translates them with glossary enforcement, and commits them back. By the time someone reviews, all languages are there. Think of it like linting or tests, but for translations.

You could wire this up yourself

And for a small project with a few languages, you should. Call an LLM API, write a validation script, keep a glossary file in your repo. There are open source tools like i18n-ai-translate and attranslate that let you bring your own API key and run translations locally. Good starting points.

But the translation itself is only one piece. The harder parts come later:

Consistency over time: How do you make sure translations stay consistent as your glossary evolves and new people join the team?
Quality validation: Who catches broken placeholders, wrong formality levels, glossary violations, or tone drift?
Compound learning: When someone on your team corrects a translation, does that correction inform future translations?
Non-technical review: Can your PM or content person review and edit translations without opening a JSON file?
Keeping it running: You built it, now you maintain it. Every edge case, every new language, every LLM API change is on your team. That's time spent on translation infrastructure instead of your product.

What I'm building to solve this

It's not worth rebuilding this infrastructure for every project. Localhero.ai is what I decided to build, a translation service for real product teams, not translators. The core idea is that everything compounds: every translation you ship, every correction someone makes, every glossary term you add feeds into making the next translation better.

One cool part is how it connects to coding agents. There's an agent skill that loads your glossary, tone settings, and naming conventions dynamically every time your agent works on translation-related code. Install it with npx skills add localheroai/agent-skill and it works with Claude Code, Cursor, and any agent that reads skills.sh skill files. If your PM adds a new term to the glossary or adjusts the style guide, every developer's agent picks that up on the next task. No syncing, no Slack messages.

On the CI side, a GitHub Action ensures everything is in sync. Every PR that touches locale files gets translated automatically with glossary enforcement, translation memory, and language-specific rules for things like German formality or Scandinavian natural register. Just write the source language and let CI handle the localization.

There's a lot more going on under the hood than just calling an LLM. Quality checks catch broken placeholders, glossary violations, and tone drift before anything lands in your PR. Every PR gets a dedicated review page where anyone on the team can edit translations inline or apply suggested fixes. And when someone corrects a translation, that decision feeds back into translation memory, so the system learns from your team's choices over time. It's like working with a translator that actually remembers what you decided last month.

It works with JSON (React, Next.js, Vue), YAML (Rails), and PO files (Django, Python). The agent skill and CLI are open source, and there's a free plan if you want to try it on a real project.

The compounding part

The thing I like most about this setup is that it gets better on its own. Every translation you ship, every correction your team makes, every glossary term you add feeds forward. Six months in, the system knows your voice better than any new hire would. That's the part you can't get from a script and an API call.

If you're shipping in multiple languages and it still feels like a separate workstream, start with the glossary. Get your team's decisions documented, give that context to your agent, and see what happens. And if you want help setting it up, reach out, happy to help.