DEV Community: Diogo Heleno

Building a Terminology Pipeline for Multilingual SOPs (So Translators Don't Reinvent Your Vocabulary Every Cycle)

Diogo Heleno — Fri, 13 Nov 2026 09:35:44 +0000

A badly translated SOP isn't a copywriting problem, it's a data consistency problem. If your company runs branches in multiple countries, the SOP that gets translated for São Paulo and the one that gets translated for Luanda should use the exact same term for "batch," the exact same modal verb for "must," and the exact same reference to the regulatory clause. In practice, that almost never happens, because most teams treat translation as a one-off task instead of a pipeline with state.

This article from M21Global lays out why SOP translation deserves special handling compared to other technical documents, focusing on linguistic registers, review tiers and formatting. Worth reading if you're the one requesting the translation. This post is for the people who have to manage the documents and versions once the translated files come back: engineers, technical writers, and whoever owns the docs repo.

Treat SOP translation like you treat code localization

If you've built an i18n pipeline for a product UI, you already know the pattern: extract strings, keep a translation memory, never let two translators independently decide what "Cancel" means in Portuguese. SOPs need the same discipline, except the "strings" are full paragraphs with legal weight, and the "build" is a PDF that an auditor will read line by line.

The failure mode is identical to what happens when you don't have a single source of truth for UI strings: duplicate keys, inconsistent wording, and a maintenance nightmare the moment you need to update something globally.

Set up a terminology database before you translate anything

The fix isn't a better translator. It's infrastructure. Before any SOP goes out for translation, you need:

A controlled glossary: source term, target term per locale, definition, regulatory body reference (ANVISA, Infarmed, etc.), and approval status.
A translation memory (TM): segment-level storage of previously approved translations, so repeated or near-identical sentences get reused instead of retranslated.
A single owner for both, usually the quality team at head office, not whichever branch happens to be expanding fastest that quarter.

If you're building this in-house rather than relying entirely on your translation vendor, the tooling looks a lot like a standard localization stack:

# Example: structure for a terminology repo
/sop-l10n
  /glossary
    en-source.tbx       # TBX is the standard interchange format for term bases
    pt-BR.tbx
    pt-AO.tbx
  /tm
    project.tmx         # TMX stores aligned source/target segments
  /sop-source
    cleaning-procedure-v3.md
  /sop-translated
    cleaning-procedure-v3.pt-BR.md
    cleaning-procedure-v3.pt-AO.md

TBX (TermBase eXchange) and TMX (Translation Memory eXchange) are both open XML standards, supported by every serious CAT tool (SDL Trados, memoQ, Phrase, Smartcat). If your vendor isn't working with these formats, you can't audit or reuse their terminology decisions, and you're locked into asking them to manually track consistency across every branch.

Automating consistency checks

Once you have a glossary and TM, you can script QA checks instead of relying on a reviewer catching inconsistencies by eye. A few patterns worth automating:

import re

# Flag modal verb downgrades that change obligation into permission
RISKY_PATTERNS = [
    (r"deve", "mandatory (deve)"),      # Portuguese "must"
    (r"pode", "optional (pode)"),       # Portuguese "may"
]

def check_modal_consistency(source_text, target_text):
    """
    Flags cases where a source 'must' clause might have been
    softened to 'may' in translation. Needs a source-target
    sentence alignment first (TM tools usually provide this).
    """
    if "must" in source_text.lower() and "pode" in target_text.lower():
        return "WARNING: possible obligation downgrade"
    return "OK"

This is intentionally simplistic, real implementations should work on aligned segments from your TM rather than raw text diffing, but the point is: the same regex/linting mindset you apply to catching bugs in code can catch regulatory risk in translated SOPs. Nobody should be manually re-reading 40-page documents to catch a single "must" that became a "may."

Version control for translated documents

Treat translated SOPs the way you treat compiled artifacts: never hand-edit them independently from the source. A sane setup:

Source SOP lives in your main docs repo (Markdown, DITA, whatever you use).
Each translation is a build output tied to a specific source commit/version.
When the source changes, diff against the last translated commit and only send the delta to translators, not the whole document.
Store the mapping (source version → translated version → translator → review status) somewhere queryable, not in a spreadsheet nobody updates.

# sop-manifest.yaml
document: cleaning-procedure
source_version: v3.2
source_commit: a1b2c3d
translations:
  pt-BR:
    version: v3.2
    translator: vendor-x
    reviewed_by: qa-team-brazil
    status: approved
  pt-AO:
    version: v3.1   # lagging behind source, needs retranslation
    translator: vendor-y
    reviewed_by: null
    status: pending

This manifest alone will tell you, at a glance, which branches are running on outdated SOP translations, which is exactly the kind of gap that turns into a non-conformance during an audit.

Where this intersects with review tiers

The source article breaks down review tiers by audit exposure: full dual-linguist review for anything an external auditor will see, lighter review for internal-only documents. That maps cleanly onto a CI/CD-style promotion model if you want to formalize it:

Draft → machine translation + glossary pass, internal use only.
Staging → single linguist + glossary/TM enforcement, for internal procedure manuals.
Production → dual linguist review + QA, for anything audit-facing or regulator-facing.

Documents shouldn't move to "production" status until they pass the same kind of checklist you'd apply to a release: terminology check, formatting diff against source, control header fields intact, modal verb consistency pass.

The real cost isn't translation, it's drift

None of this is about mistrusting translators. It's about recognizing that the moment you have more than one branch and more than one language, SOP translation stops being a single task and becomes a system with state that can drift out of sync. Drift is what turns into a flagged non-conformance two years later, when nobody remembers why the Angola version says something subtly different from the Brazil version.

If your organization is translating SOPs for multiple international branches, it's worth asking your vendor directly whether they maintain a shared glossary and TM across all your projects, or whether each branch effectively starts from zero. That answer tells you more about long-term translation quality than any single document review.

Building a Terminology Validation Pipeline for CPNP Cosmetic Dossiers

Diogo Heleno — Thu, 12 Nov 2026 09:04:40 +0000

Regulatory translation for cosmetics has a nasty failure mode: the document reads perfectly well in the target language, passes a normal QA check, and is still non-compliant. INCI ingredient names get localized when they shouldn't be, standardized safety warnings get reworded for "flow", and claims like hypoallergenic get translated literally into markets where that word carries different legal weight.

The source article on CPNP documentation translation covers the regulatory side of this well: what Regulation (EC) No 1223/2009 requires, which documents need translation, and where human review needs to happen. This article is about the complementary problem: if you're building or maintaining the software systems that generate, manage, or submit cosmetic product documentation, how do you catch these errors before they reach a translator or a regulator?

The problem is structural, not linguistic

Most translation QA tooling checks for things like terminology consistency, tone, and glossary adherence. None of that catches a correctly translated sentence that is still non-compliant. You need a layer that understands:

Which strings in your content model must never be translated (INCI names)
Which strings must match an approved, standardized wording exactly (safety warnings)
Which strings are free text but trigger regulatory review if certain terms appear (claims)

This is a classification problem you can solve with tooling, independent of whatever translation vendor or workflow you use downstream.

Tagging content at the source

If your product content lives in a CMS, PIM, or structured XML/JSON dossier format, the fix starts at the schema level. Don't let ingredient lists live as plain strings next to marketing copy. Tag them.

{
  "product_id": "SKU-4471",
  "ingredients": {
    "type": "inci_list",
    "locked": true,
    "values": ["Aqua", "Glycerin", "Retinol", "Parfum"]
  },
  "warnings": {
    "type": "standardized_regulatory_text",
    "ref_id": "EU-RETINOL-WARNING-01",
    "locked": true
  },
  "claims": {
    "type": "marketing_claim",
    "locked": false,
    "flagged_terms": ["hypoallergenic", "dermatologically tested"]
  }
}

The locked flag is the important part. It's a signal to every downstream system, translation memory tool, CAT tool, CMS export script, that this field should not be touched by free translation. It should either pass through unchanged (INCI) or be swapped for a pre-approved equivalent (standardized warnings).

A validation script, not a full pipeline

You don't need a complex system to catch most of these errors. A pre-submission linter that runs against your exported dossier before it goes to CPNP or to a translation vendor catches a large share of mistakes for very little effort.

import re

INCI_PATTERN = re.compile(r'^[A-Z][a-zA-Z\s\-]+$')
FLAGGED_CLAIMS = ["hypoallergenic", "dermatologically tested", "paraben-free", "clinically proven"]

def validate_ingredients(ingredient_list, translated_list):
    errors = []
    for original, translated in zip(ingredient_list, translated_list):
        if original != translated:
            errors.append(f"INCI mismatch: '{original}' became '{translated}'")
        if not INCI_PATTERN.match(translated):
            errors.append(f"Suspicious INCI format: '{translated}'")
    return errors

def flag_claims(text):
    found = [term for term in FLAGGED_CLAIMS if term.lower() in text.lower()]
    return found

def validate_warning_block(warning_text, approved_text_map, ref_id, locale):
    approved = approved_text_map.get((ref_id, locale))
    if approved and warning_text.strip() != approved.strip():
        return [f"Warning text for {ref_id} ({locale}) does not match approved wording"]
    return []

This isn't production-grade, but it illustrates the shape of the check: diff against a source of truth, don't just spellcheck. The INCI check alone, a straight string comparison between source and translated ingredient fields, would have caught the most common error type the source article describes.

Maintaining an approved-text database

Standardized warnings (retinol, UV filters, acids) exist in finite, enumerable sets per locale. If you're dealing with more than a handful of SKUs, it's worth maintaining these as a lookup table rather than trusting that each translator or CAT tool has the current approved wording.

CREATE TABLE approved_warnings (
    ref_id VARCHAR(50),
    locale VARCHAR(10),
    text TEXT,
    regulation_ref VARCHAR(100),
    last_updated DATE,
    PRIMARY KEY (ref_id, locale)
);

When regulatory wording changes (and it does, EU cosmetics legislation gets amended), you update one table instead of hunting through every product's labelling file. Your CI pipeline, if you have one for content, can run a job that flags any product referencing a ref_id whose last_updated predates the latest known regulation version.

Where this fits with translation vendors

None of this replaces a qualified translator or a second-linguist review for the documents that carry legal weight, the CPSR, safety data sheets, and labelling with claims. What it does is reduce the number of errors that reach that review stage, and it gives your translation vendor a clean signal about which fields are locked versus which are open for localization. Sending a vendor a dossier where ingredient fields are explicitly tagged locked: true is a lot less error-prone than trusting that every translator in the chain knows INCI nomenclature by heart.

If you're integrating with CPNP or managing a PIF (Product Information File) across multiple markets, the pre-submission validation pattern scales reasonably well: tag your content model, diff locked fields automatically, maintain approved text as data instead of as tribal knowledge in a style guide nobody reads.

Takeaway

Regulatory compliance for cosmetics translation is ultimately a data integrity problem wearing a legal costume. Treat INCI names, standardized warnings, and flagged claims as structured, validated fields in your content pipeline, not as free text that happens to go through a translation step, and you'll catch most of the expensive mistakes before they reach a regulator or a market surveillance inspector.

Building a Document Requirements Checker for International Civil Registration Workflows

Diogo Heleno — Thu, 12 Nov 2026 07:08:06 +0000

Certified document translation sits at an odd intersection: it looks like a pure compliance problem, but in practice it's a workflow and data validation problem. If you've ever built internal tools for an immigration law firm, an HR team handling relocations, or a product that touches cross-border civil processes (marriage registration, visa sponsorship, dual citizenship), you've probably run into the same mess the source article describes from a non-technical angle: certified translation requirements for marriage certificates vary wildly by destination country, and getting the sequence wrong costs weeks.

That article is written for people navigating the process manually. This one is for people who want to model it as a system.

Why this is a graph problem, not a form problem

Most teams start by building a form: upload document, pick destination country, get a checklist. That works until you realize the requirements aren't independent fields, they're a dependency graph.

Whether you need an apostille or consular legalisation depends on whether the destination country is a Hague Convention signatory.
Whether the translation needs to be apostilled before or after translation depends on the destination registry, not just the country.
Document validity windows (e.g., "certificate must be issued within 6 months") are destination-specific and time-relative to submission date, not issuance date.
Some destinations require translating supporting documents (birth certificates, prior divorce decrees) only conditionally, based on facts about the applicant (was either party previously married?).

Modeling this as a flat checklist breaks the moment you have conditional requirements. A better fit is a rules engine over a small graph: country → convention status → document chain → conditional sub-documents.

A minimal data model

Here's a simplified schema that captures the real structure instead of hardcoding per-country logic in application code:

from dataclasses import dataclass, field
from enum import Enum
from datetime import date, timedelta

class LegalizationType(Enum):
    APOSTILLE = "apostille"
    CONSULAR_LEGALIZATION = "consular_legalization"
    NONE = "none"

@dataclass
class CountryRequirement:
    country_code: str
    hague_member: bool
    legalization: LegalizationType
    translation_order: str  # "translate_then_legalize" | "legalize_then_translate"
    certificate_validity_days: int
    requires_sworn_translator: bool

@dataclass
class ApplicantFacts:
    previously_married_either_party: bool
    destination_requires_individual_civil_records: bool

def build_document_checklist(req: CountryRequirement, facts: ApplicantFacts, issue_date: date, today: date):
    checklist = ["original_marriage_certificate"]

    if today - issue_date > timedelta(days=req.certificate_validity_days):
        raise ValueError("Certificate exceeds validity window — request a new one before proceeding")

    if req.legalization == LegalizationType.APOSTILLE:
        checklist.append("apostille")
    elif req.legalization == LegalizationType.CONSULAR_LEGALIZATION:
        checklist.append("foreign_ministry_authentication")
        checklist.append("consular_legalization")

    checklist.append("certified_translation")

    if facts.destination_requires_individual_civil_records:
        checklist.append("birth_certificates_both_spouses")

    if facts.previously_married_either_party:
        checklist.append("divorce_decree_or_death_certificate")

    return checklist

This is deliberately simple, but the point stands: encode country rules as data, not as if country == "Angola" scattered across your codebase. Store CountryRequirement records in a database table or config file, version them, and you get an audit trail when rules change (and they do change — consular requirements update without much notice).

The Hague Convention lookup isn't optional config, it's a maintained dataset

Don't hardcode the list of Hague Apostille Convention members. It changes. As of the article's example, Angola and Mozambique are not members, so documents bound there always need consular legalisation regardless of where the source document originated. Build this as a small, separately versioned dataset you can update independently of your application release cycle:

{
  "PT": { "hague_member": true },
  "DE": { "hague_member": true },
  "BR": { "hague_member": true },
  "AO": { "hague_member": false },
  "MZ": { "hague_member": false }
}

Pull this from a maintained source (HCCH publishes the official member list) rather than trusting a static array someone wrote two years ago.

Validity windows are a scheduling problem, not a validation problem

The "certificate must be issued within X months" rule is where most manual processes actually fail, per the source article. This is solvable with basic date math, but the more useful engineering move is proactive: if you're building a case management tool, flag certificates approaching their expiry window before submission, not after rejection.

def days_until_expiry(issue_date: date, validity_days: int, today: date) -> int:
    return validity_days - (today - issue_date).days

# Surface a warning if fewer than 30 days remain before the certificate
# becomes stale relative to the destination's validity window

If your tool integrates with a translation vendor's API or intake form, trigger a reorder of the source certificate automatically when this threshold is crossed, instead of letting the applicant find out at submission time.

Translator credentialing as a verifiable attribute, not a free-text field

If you're building intake forms for translation vendors or law firms, don't store "translator qualification" as a free-text string. Destination countries check for specific credential types: court-sworn status, chamber registration, ISO 17100 workflow compliance (independent second-linguist review). Model it as an enum or tag set so you can filter and match translator pools against destination requirements programmatically:

class TranslatorCredential(Enum):
    COURT_SWORN = "court_sworn"
    CHAMBER_REGISTERED = "chamber_registered"
    ISO_17100_CERTIFIED = "iso_17100"
    SELF_DECLARED = "self_declared"

This matters in practice: a translation produced under ISO 17100 (independent review by a second linguist) is a different compliance artifact than a self-declared accuracy statement, even if the output text is identical. If you're automating vendor selection, this is the field to filter on.

Takeaway

The underlying process the source article walks through manually — check destination rules, confirm Hague status, sequence apostille and translation correctly, validate certificate age, assemble conditional sub-documents — maps cleanly onto a rules engine with versioned country data and a small dependency graph. If you're building tooling for immigration, relocation, or civil registration use cases, resist the urge to hardcode country logic into application code. Treat it as config, version it, and build expiry/validity checks as proactive alerts rather than post-submission failures.

For the actual translation work, you still need a human translator with the right legal credential for the destination — that part doesn't automate. But everything around it (sequencing, validity checks, conditional document sets) is a solvable engineering problem most teams are still doing by hand in spreadsheets.

Building a Localization Pipeline for EU Digital Product Passport Data

Diogo Heleno — Wed, 11 Nov 2026 16:34:46 +0000

The EU's Digital Product Passport (DPP) is one of those regulations that looks like a legal problem until you actually start implementing it, and then it turns into a very concrete data engineering problem. You end up with structured product data, multiple target languages per market, a QR code pointing to a live endpoint, and a compliance deadline. That's a systems design challenge, not just a translation task.

The M21Global article on DPP translation requirements does a good job covering the regulatory side: which documents need what level of review, and why a mistranslated substances-of-concern field can trigger a non-conformity rather than just a bad review. This post covers the other half: how to actually build the pipeline that keeps multilingual DPP content in sync with your product data as it changes.

Why this isn't a normal i18n problem

If you've built multilingual product pages before, your instinct is to treat this like standard i18n: extract strings, send to a translation service, get them back, render per locale. DPP content breaks that model in a few ways:

It's not UI copy, it's regulatory data with legal weight. A translated field isn't just displayed, it's audited.
It needs to stay tied to structured formats (XML/JSON) that feed ERPs, catalogue systems, and the actual QR code endpoint.
Different fields have different risk levels, so they can't all go through the same translation/review tier.
Source content changes continuously as products get updated, recalled, or re-certified, so this is a living pipeline, not a one-time export.

So instead of a string-extraction tool, think of this as a content sync problem between your PLM/ERP system, a translation layer, and whatever renders the public-facing passport.

Structuring the data so translation doesn't break it

First problem to solve: keep translation changes scoped to translatable fields only, and never touch structure, units, or identifiers.

A reasonable schema separates regulatory fields from descriptive fields explicitly, so you can route them differently later:

{
  "product_id": "SKU-48213",
  "category": "regulatory",
  "field": "substances_of_concern",
  "source_lang": "pt",
  "value": "Contém 0,08% de ftalato de dibutilo (DBP)",
  "translatable": true,
  "risk_level": "high"
}

{
  "product_id": "SKU-48213",
  "category": "descriptive",
  "field": "marketing_description",
  "source_lang": "pt",
  "value": "Cadeira ergonómica fabricada com materiais reciclados",
  "translatable": true,
  "risk_level": "low"
}

The risk_level field is the key addition. It lets you route content programmatically to the correct review tier instead of deciding manually per document, which doesn't scale past a few hundred SKUs.

Routing content by risk level

Once fields are tagged, you can build a simple router that decides the translation workflow:

def route_for_translation(field):
    if field["risk_level"] == "high":
        return "TEP"       # translate + edit + proofread, second linguist review
    elif field["risk_level"] == "medium":
        return "MTPE"      # machine translation + full post-edit
    else:
        return "MT_light"  # light post-edit or no review

for field in product_fields:
    if field["translatable"]:
        workflow = route_for_translation(field)
        queue_for_translation(field, workflow)

This maps directly onto the tiered approach described in the source article (TEP for regulatory content, lighter MTPE-based workflows for high-volume descriptive content). The point of automating the routing is that nobody has to manually decide, SKU by SKU, whether a field is sensitive enough for a second linguist. You decide that once, at the schema level, and the pipeline enforces it.

Keeping terminology consistent at scale

Terminology drift is the real failure mode here, not bad grammar. If "recyclable packaging" gets translated three different ways across your catalogue, that's a compliance inconsistency waiting to be flagged.

If you're working with CAT tools or an LSP, make sure:

A termbase (TBX format works well) is maintained per product line, not per project
Translation memory (TMX) is reused across updates, not regenerated from scratch each release
Any machine translation step is constrained by the termbase, not run freely

If you want a lightweight internal check before content even reaches translation, a simple glossary validation script catches obvious drift:

import json

def validate_terminology(text, glossary):
    violations = []
    for term, approved in glossary.items():
        if term.lower() in text.lower() and approved.lower() not in text.lower():
            violations.append((term, approved))
    return violations

glossary = json.load(open("product_line_glossary.json"))
violations = validate_terminology(source_text, glossary)

This won't replace a human reviewer on regulatory content, but it catches obvious inconsistency before it ever reaches a translator, which saves review cycles.

Keeping the QR code endpoint in sync

The DPP has to be live and queryable, which means your translated content needs a versioning strategy, not just a one-time push. A few practical points:

Version every field, not just the document. If a certificate gets re-issued, you need to know which language versions are stale.
Treat the QR endpoint as an API, with locale as a query parameter or path segment (/dpp/SKU-48213/en, /dpp/SKU-48213/de), not a static generated file per language.
Add a last_verified timestamp per language version, separate from last_updated on the source, so you can flag when a translation is lagging behind a source change.

{
  "product_id": "SKU-48213",
  "lang": "de",
  "source_updated": "2025-03-10",
  "translation_updated": "2025-03-09",
  "status": "stale"
}

That status field is cheap to compute and extremely useful operationally: it's your early warning system for compliance drift across markets.

Where this leaves you

None of this replaces having a qualified linguist review your declarations of conformity, that part is non-negotiable and well covered in the source article. But the engineering work around it, tagging risk level, routing content, versioning translations against source changes, catching terminology drift before it reaches a human reviewer, is what determines whether this scales to a few thousand SKUs across a dozen EU markets or collapses into a spreadsheet nobody trusts.

If you're building this now, start with the schema. Everything else (routing, versioning, glossary checks) falls out naturally once risk level and translation status are first-class fields in your product data, not an afterthought bolted on at export time.

Tracking Multi-Language Document Pipelines: What Immigration Paperwork Can Teach Us About Data Integrity

Diogo Heleno — Mon, 09 Nov 2026 08:28:36 +0000

Immigration paperwork isn't something most developers think about, until they're the ones applying for a visa and realize their diploma, contract, and criminal record certificate all need certified translation before a government agency will even look at them.

A recent article from M21Global (Certified Translation for EU Blue Card Applications) breaks down the document requirements for EU Blue Card applications filed with AIMA in Portugal. It's a solid read if you're navigating that specific process. But reading it through a technical lens surfaced something more generally interesting: this is fundamentally a data consistency problem across untrusted, human-generated inputs, and it's one we deal with constantly in software, just with different stakes.

If you've ever built an onboarding pipeline for KYC documents, multi-language form validation, or any system that ingests user-submitted PDFs and needs to reconcile names, dates, and identifiers across sources, this will feel familiar.

The core problem: cross-document consistency

The source article flags this as one of the most common failure points:

Inconsistent names across documents: the spelling of names must match exactly across all translated documents, including accents and surname order.

This is a string-matching and normalization problem, and it's exactly the kind of thing that should never be handled by eyeballing a stack of PDFs.

If you're building (or advising on) a document intake system that handles multilingual identity documents, here's a practical approach:

1. Normalize before you compare

Names with diacritics, transliterated scripts, and surname-order differences (given-name-first vs. family-name-first) break naive string equality checks immediately.

import unicodedata

def normalize_name(name: str) -> str:
    # Strip accents, lowercase, collapse whitespace
    nfkd = unicodedata.normalize('NFKD', name)
    ascii_name = nfkd.encode('ASCII', 'ignore').decode('utf-8')
    return ' '.join(ascii_name.lower().split())

normalize_name("José María García-López")
# 'jose maria garcia-lopez'

This won't solve surname-order ambiguity on its own, but it eliminates the most common false mismatches before you even get to semantic comparison.

2. Use fuzzy matching with a human review gate

Don't auto-reject or auto-approve on fuzzy match scores. Use something like rapidfuzz to flag documents for review rather than making binary pass/fail decisions.

from rapidfuzz import fuzz

score = fuzz.token_sort_ratio(
    normalize_name("Ana Paula Silva"),
    normalize_name("Silva, Ana Paula")
)
# token_sort_ratio handles word-order differences

Set a threshold (say, 90+) for auto-pass, and route anything below that to a human reviewer instead of a hard rejection. The cost of a false rejection in a visa pipeline is an angry user and a support ticket; the cost of a false pass is a compliance problem.

Apostilles and certification chains as a dependency graph

The article also describes something that maps cleanly onto a concept developers already understand: dependency resolution.

For applicants bringing documents from countries that are party to the Hague Apostille Convention, the original document may also need an apostille in the country of issue before translation.

That's a prerequisite step that has to complete before the next step (translation) can even start, and the required chain differs by country of origin. If you're designing a checklist tool or intake form for this kind of process (and plenty of relocation/immigration SaaS products exist to do exactly this), model it as a directed graph rather than a flat checklist:

const documentRequirements = {
  diploma: {
    requiresApostille: (country) => hagueConventionCountries.includes(country),
    requiresCertifiedTranslation: (lang) => lang !== 'pt' && lang !== 'en',
    dependencies: ['apostille'], // must exist before translation step
  },
  criminalRecord: {
    requiresApostille: (country) => hagueConventionCountries.includes(country),
    requiresCertifiedTranslation: (lang) => lang !== 'pt',
    dependencies: ['apostille'],
  },
};

A flat checklist UI ("have you translated your documents? yes/no") hides ordering requirements that cause real rework. A graph-based model, even a simple one, lets you surface the correct sequence to the user and block premature steps.

Building a lightweight i18n document tracker

If you're a freelance developer or building internal tooling for an immigration law firm, relocation agency, or HR department handling visa sponsorships, a minimal tracker doesn't need to be complex. The core entities are:

Document (type, source language, issuing country, issue date)
CertificationStatus (none, apostilled, translated, certified)
ValidationFlag (name mismatch, missing annex, terminology concern)

CREATE TABLE documents (
    id UUID PRIMARY KEY,
    applicant_id UUID NOT NULL,
    doc_type TEXT NOT NULL, -- 'diploma', 'contract', 'criminal_record'
    source_lang TEXT NOT NULL,
    issuing_country TEXT NOT NULL,
    needs_apostille BOOLEAN DEFAULT FALSE,
    apostille_obtained_at TIMESTAMP,
    certified_translation_at TIMESTAMP,
    status TEXT DEFAULT 'pending' -- pending, flagged, approved
);

CREATE TABLE validation_flags (
    id UUID PRIMARY KEY,
    document_id UUID REFERENCES documents(id),
    flag_type TEXT NOT NULL, -- 'name_mismatch', 'missing_annex', 'terminology'
    notes TEXT,
    resolved BOOLEAN DEFAULT FALSE
);

This gives you queryable state instead of a shared spreadsheet, which is still how a surprising number of relocation cases get tracked today.

Terminology mapping is a translation memory problem

One detail in the source article is worth calling out for anyone working on localization tooling:

Academic terminology poorly rendered: degrees, institutions and fields of study need to correspond to the Portuguese education system or to a formulation AIMA can recognise.

This isn't a "translate word for word" problem, it's an equivalence-mapping problem, similar to currency or unit conversion but for institutional terms. If you're building tooling for certified translators (or integrating with services like M21Global's legal translation workflow), a termbase or translation memory system (TMX format, or a simple key-value store per jurisdiction) pays for itself quickly:

{
  "source_term": "Bachelor of Science",
  "source_lang": "en",
  "target_lang": "pt-PT",
  "target_term": "Licenciatura",
  "jurisdiction": "PT",
  "notes": "Not 'Bacharelato' - that term is used differently in PT-PT vs PT-BR"
}

This kind of mapping, maintained centrally and reused across cases, is exactly how certified translation agencies avoid the inconsistency that gets applications bounced back by agencies like AIMA.

Takeaway

The original article is aimed at people filing EU Blue Card applications and explains, correctly, why Portugal's certification process (lawyer or notary sign-off, not a sworn translator) differs from what applicants from Brazil or Spain might expect. That's valuable domain knowledge if you're the one filing.

But if you're building tools adjacent to this space, immigration tech, relocation platforms, HR systems for international hires, the underlying patterns (fuzzy identity matching, dependency-ordered document workflows, and terminology equivalence mapping) are the same problems you'd solve in any system that has to reconcile human-submitted, multilingual, multi-jurisdiction data. Worth building for, even outside the immigration context.

Building a Terminology Pipeline for Multilingual Pitch Decks (Before Your Series A Blows Up)

Diogo Heleno — Mon, 09 Nov 2026 07:05:02 +0000

A startup I worked with raised a seed round in Lisbon, then went to raise a Series A from a UK fund. Same company, same numbers, same traction. Three different people translated three different documents (the deck, the financial model notes, and the term sheet summary) over three weeks, with no shared glossary. The result: "receita" became "revenue" in one file and "turnover" in another, ARR was calculated two different ways in the deck versus the model, and the investor's associate flagged it in the first due diligence call.

Nobody lost the round over this, but it cost a week of clarifying emails during a period when speed matters more than almost anything else. The source article on pitch deck translation for funding rounds covers why this happens from a linguistic and financial-register perspective. This post covers it from the other side: how to build a pipeline so it doesn't happen to your documents, using tools you probably already have access to.

The actual problem is version control, not translation quality

Treat a pitch deck, a financial model, a term sheet and a data room as what they actually are: a distributed system with no single source of truth for terminology. Every document is edited independently, often by different people, often under deadline pressure, and nothing enforces consistency between them.

This is a solved problem in software. We just don't usually apply the solution to fundraising docs.

Step 1: build a glossary as a structured data file, not a spreadsheet tab

Skip the shared Google Sheet that three people forget to check. Define your glossary as a JSON or YAML file that lives in version control alongside your docs.

# glossary.yml
terms:
  - source: "receita recorrente mensal"
    target_en: "MRR"
    context: "financial_metric"
    do_not_translate_as: ["monthly recurring income", "monthly revenue"]
  - source: "taxa de queima"
    target_en: "burn rate"
    context: "financial_metric"
  - source: "pré-money"
    target_en: "pre-money valuation"
    context: "cap_table"
  - source: "quadro de capital"
    target_en: "cap table"
    context: "cap_table"

This gives you something machines and humans can both check against. Translators (human or AI-assisted) get an authoritative reference. You get something you can lint.

Step 2: lint your documents against the glossary

If your deck and financial model exist as Markdown, plain text exports, or even extracted PDF text, you can write a basic consistency checker in a few lines:

import yaml
import re

def load_glossary(path):
    with open(path) as f:
        return yaml.safe_load(f)["terms"]

def check_consistency(doc_text, glossary):
    issues = []
    for term in glossary:
        forbidden = term.get("do_not_translate_as", [])
        for bad_phrase in forbidden:
            if re.search(bad_phrase, doc_text, re.IGNORECASE):
                issues.append(
                    f"Found '{bad_phrase}', expected '{term['target_en']}'"
                )
    return issues

glossary = load_glossary("glossary.yml")
with open("financial_model_notes.txt") as f:
    text = f.read()

for issue in check_consistency(text, glossary):
    print(issue)

This is intentionally simple. You can extend it with fuzzy matching, number format validation (comma vs. period decimal separators are a real recurring bug, not a nitpick), or plug it into a CI step that runs every time someone updates a document in your data room repo.

Step 3: catch number formatting bugs explicitly

The article mentions this and it deserves its own validation step, because it's a silent, high-severity bug. Portuguese uses comma as decimal separator and period as thousands separator. English does the reverse. A number like 1.500.000,00 becomes 1,500,000.00, and if that conversion gets fumbled, your ask or valuation can silently change by a factor of a thousand.

def convert_pt_to_en_number(value_str):
    # Portuguese: 1.500.000,50 -> English: 1500000.50
    cleaned = value_str.replace(".", "").replace(",", ".")
    return float(cleaned)

assert convert_pt_to_en_number("1.500.000,50") == 1500000.50

Run every number that appears in your deck, model, and term sheet through a function like this, then diff the output against what a human translator actually typed into the English version. This catches the single costliest class of error in the entire process.

Step 4: treat your data room as a monorepo with a translation memory

Tools like Weblate, POEditor, or even a translation memory file in the TMX format let you store approved translations of recurring phrases and reuse them automatically across documents. If you're already using an LLM to draft or review translations, feed it the glossary as context rather than letting it improvise terminology per document:

system_prompt = f"""
You are translating investor-facing financial documents from Portuguese to English.
Use only the following approved terminology. Do not substitute synonyms:
{glossary_as_text}
Maintain investor-English register: direct, quantified, no unsupported adjectives.
"""

This won't replace a certified human translator for legal documents like articles of association or board resolutions, where certification and notarisation requirements apply (the source article covers this well, including the Angola-specific case). But for the deck, one-pager, and financial model notes, a glossary-constrained review pass catches most of the drift before it reaches a human reviewer.

Step 5: automate the diff check before every send

Before sending an updated deck to an investor, run a quick script that extracts every number and every glossary term from the new version and diffs it against the previous approved version and the financial model. If MRR changed in the deck but not in the model, or a number's decimal placement looks suspicious, you want that flagged before the investor sees it, not after.

# simple pre-send check
python extract_terms.py deck_v3.md > deck_terms.txt
python extract_terms.py financial_model.md > model_terms.txt
diff deck_terms.txt model_terms.txt

Where this fits with professional translation

None of this replaces a qualified translator for the documents that require certification, or a native-speaker review pass for tone and register, which is where the real skill of adjusting "innovative and disruptive" into something an investor actually trusts lives. What it does is remove the class of error that has nothing to do with translation quality and everything to do with process: inconsistent terms across documents, silent number formatting bugs, and last-minute edits that don't propagate everywhere they should.

If you're raising across borders, build the glossary and the lint step before the round opens, the same way you'd set up CI before a product launch. It's cheap insurance against the kind of mismatch that makes an investor's associate start asking questions you'd rather answer on your own terms.

Building an i18n Pipeline for API Docs That Doesn't Break Every Release

Diogo Heleno — Sun, 08 Nov 2026 07:06:12 +0000

The problem nobody budgets for

If you've ever maintained a developer portal, you know the docs change faster than anyone wants to admit. New endpoint, new param, deprecation notice, a fixed typo in a code sample — it never stops. Now add translation into that mix and most teams panic and either give up on localisation entirely or bolt on a manual process that breaks within two releases.

There's a good write-up on the content and terminology side of this problem in this article on API documentation localisation. It covers why API docs need different handling than a user manual: code should never be translated, terminology has to stay locked across every page, and the whole thing is a moving target instead of a static document.

That's the editorial side. This post is about the plumbing: how to actually wire translation into a docs pipeline that's built on Git, Markdown, and CI, without it turning into a manual copy-paste nightmare every sprint.

Don't translate the whole file, translate the diff

The single biggest mistake teams make is sending the entire docs repo to translation every time something changes. If you have 300 pages of OpenAPI-generated reference and you change one endpoint, you don't need 299 pages retranslated — you need a diff-based workflow.

A reasonable setup looks like this:

# Generate a diff of changed docs since last translated commit
git diff last-translated-tag HEAD -- docs/ > changes.diff

# Extract only the files with actual content changes (not formatting)
git diff --name-only last-translated-tag HEAD -- docs/*.md docs/*.mdx

Feed only the changed files into your translation step, then re-tag once the translated version comes back:

git tag last-translated-tag HEAD

This is the same mental model as incremental builds. Translating everything every time is like rebuilding your entire project instead of just the changed modules — it works, but it doesn't scale and it reintroduces risk into sections that were already reviewed.

Keep translatable strings out of your code blocks

If your docs are Markdown/MDX with embedded code fences, you need a convention that strictly separates translatable prose from non-translatable code. Most localisation tools (and humans) will happily try to "helpfully" translate a JSON key if you don't fence it off clearly.

<!-- GOOD: comment is translatable, code stays untouched -->

json
{
"access_token": "ya29.a0AfH6...", // short-lived token, expires in 1h
"token_type": "Bearer"
}

markdown

A few rules worth enforcing with a linter or pre-commit hook:

Code fences ( ``` ) are never sent to translation as a whole block. Only inline comments inside them are candidates, and only if your team has explicitly approved translating comments.
JSON field names, HTTP headers, and status codes are never translated, full stop. This is a technical convention most API consumers expect, even in localised docs.
Markdown front matter (YAML metadata) needs its own extraction rule, since it often contains both translatable text (title:) and non-translatable config (slug:, api_version:).

Tools like gettext, or frameworks with first-class i18n support (Docusaurus i18n, Next.js with next-intl), handle this separation well if you structure content correctly from the start. Retrofitting it onto a repo that mixes everything into prose paragraphs is painful.

Structuring resource files vs. prose content

API portals typically have two very different kinds of translatable content, and they shouldn't go through the same pipeline:

UI strings (buttons, tooltips, error banners) belong in structured resource files:

// en/portal.json
{
  "button.tryItOut": "Try it out",
  "error.rateLimited": "You've hit the rate limit. Try again in {seconds}s."
}

// fr/portal.json
{
  "button.tryItOut": "Essayer",
  "error.rateLimited": "Limite de requêtes atteinte. Réessayez dans {seconds}s."
}

These are small, stable, and rarely change — a good candidate for full human review since a bad translation here shows up directly in the product UI.

Long-form docs (guides, quickstarts, endpoint descriptions) live in Markdown and change constantly. These need the diff-based workflow above, plus a translation memory (TM) so repeated phrases ("Returns a 401 if the token is invalid") don't get retranslated — and potentially re-worded — every single time they appear on a new page.

A minimal glossary enforcement script

Terminology drift is the real failure mode, not bad grammar. If "rate limit" gets translated three different ways across your docs, that's worse than leaving it in English everywhere. A cheap way to catch this in CI before it ships:

import re
import sys

GLOSSARY = {
    "limite de débit": "limite de requêtes",  # banned -> approved
    "jeton d'accès": "token d'accès",
}

def check_file(path):
    with open(path, encoding="utf-8") as f:
        text = f.read()
    errors = []
    for banned, approved in GLOSSARY.items():
        if re.search(banned, text, re.IGNORECASE):
            errors.append(f"{path}: found '{banned}', use '{approved}' instead")
    return errors

if __name__ == "__main__":
    all_errors = []
    for path in sys.argv[1:]:
        all_errors.extend(check_file(path))
    if all_errors:
        print("\n".join(all_errors))
        sys.exit(1)

Run this as a pre-merge check on any translated Markdown file. It won't catch everything, but it stops the most common regressions: a translator or MT engine reintroducing a term that was already standardized months ago.

Automated vs. human review, mapped to risk

Not every page deserves the same review budget, and this maps surprisingly well to standard software risk triage:

Auto-generated reference pages (hundreds of near-identical endpoint descriptions from your OpenAPI spec): machine translation with spot checks is usually fine. The repetitive structure means errors are easy to catch with the glossary script above.
Guides that directly affect integration success (auth flows, webhooks setup, error handling): these need a human reviewing full text, because a misunderstood paragraph here generates support tickets, not just an awkward sentence.
Anything customer-facing in a sales context (docs an enterprise prospect reads before signing): treat it like marketing copy — full review pass, consistent tone, the works.

Testing localised docs like you'd test a UI

Once translated content is merged, don't assume it's done. German and Finnish strings run 20-35% longer than English on average, and that breaks fixed-width code sample containers, nav sidebars, and button layouts. Run your localised build through the same visual regression tests you'd use for any UI change:

# Example with Percy or a similar visual diff tool
npx percy exec -- npm run build:docs -- --locale=de

If you don't have visual regression testing set up for your docs site, this alone is worth adding before you scale to a third or fourth language.

Wrapping up

Localising API docs isn't a translation problem bolted onto a docs problem — it's a pipeline problem. The teams that get it right treat translated content the same way they treat code: versioned, diffed, linted, and tested before it ships. The source article does a good job covering the terminology and tiering side of this; the engineering side is just as much work, and it's the part that determines whether your localised docs stay correct past the first release.

Building a Multilingual Policy Pipeline: A Technical Approach to GDPR/LGPD Documentation

Diogo Heleno — Sat, 07 Nov 2026 07:03:39 +0000

If you work at a company with employees across multiple countries, you've probably seen this pattern: legal/compliance drops a new data protection policy in a shared drive, HR sends a link, and someone in the Luanda or São Paulo office opens a PDF written in dense European Portuguese or English legalese. Nobody reads it. If there's ever an audit or a dispute, that's a problem.

There's a good write-up on the legal side of this from M21Global, covering what GDPR, Angola's Law No. 22/11, and Brazil's LGPD actually require in terms of linguistic clarity. That article is aimed at compliance teams deciding whether to hire a translation service. This one is for the people who end up building and maintaining the actual document pipeline, because "just translate the policy" turns into a surprisingly gnarly content-ops problem once you have more than two jurisdictions.

Why this isn't a one-off translation task

A data protection policy isn't static. It changes when:

Legislation changes (new guidance from a supervisory authority, amendments to local law)
The org changes (new data processors, new retention periods, new subsidiaries)
Internal tooling changes (new HR system, new vendor handling payroll data)

If you're maintaining four jurisdiction-specific versions of the same policy by hand, in four separate Word docs, you will eventually ship a version where the GDPR complaints procedure in the Portuguese file doesn't match the one in the French file. This is a content synchronization problem, and it should be treated like one.

Treat policy documents like source code

The cleanest approach I've seen (and used) is to version-control policy content the same way you'd version-control i18n strings in an app.

1. Structure the policy as modular content, not a monolithic doc.

Break it into sections that map to legal concepts rather than paragraphs:

# policy/sections/data-controller.yml
id: data_controller_definition
source_lang: en
last_legal_review: 2024-11-03
requires_jurisdiction_adaptation: true
content:
  en: "The data controller is the entity that determines..."

This lets you flag, at the content level, which sections are pure translation versus which require legal adaptation (complaints mechanisms, supervisory authority names, specific statutory rights). That distinction matters a lot operationally — the source article makes the legal case for why "responsável pelo tratamento" isn't just a stylistic choice over "gestor de dados"; from a pipeline perspective, that means certain sections need a legal reviewer in the loop, not just a linguist.

2. Use a translation management system (TMS) with a review workflow, not raw files in a repo.

Tools like Crowdin, Phrase, or Lokalise support multi-step review pipelines (translator → reviewer → QA) and, critically, translation memory. For legal documents this matters because:

Translation memory ensures "data subject" is translated identically everywhere it appears in a given language, instead of drifting across documents translated at different times.
You can lock terminology with a glossary feature so "titular dos dados" (Brazil) vs "titular de dados" (Portugal) doesn't get mixed up between your BR and PT locales, which look similar but are legally distinct markets.

// glossary.json — enforced terms per locale
{
  "data_controller": {
    "pt-PT": "responsável pelo tratamento",
    "pt-BR": "controlador",
    "fr-FR": "responsable du traitement"
  }
}

3. Automate the diff-and-flag step when the source changes.

When the master policy changes, you want an automatic flag on every derived version showing exactly what changed, not a full re-translation. A simple approach:

# pseudo-pipeline, runs on PR to policy/source/en.md
git diff --unified=0 policy/source/en.md > changes.diff
./scripts/extract_changed_sections.py changes.diff > flagged_sections.json
# flagged_sections.json feeds into your TMS as a new translation job,
# scoped only to the changed sections

This keeps turnaround fast and cheap for minor updates (a new vendor added to a processing list) versus a full-document legal re-translation (a new retention policy across the board).

Where human legal review has to stay in the loop

Automation gets you consistency and speed, not legal accuracy. The source article's point about terminology (controller vs. processor, jurisdiction-specific complaints procedures, correct name of the supervisory authority) is the part no pipeline can fully automate. What the pipeline can do is make sure those sections are reliably routed to a qualified reviewer every time, instead of relying on someone remembering to flag them.

Practical rule of thumb for a CI-style workflow:

Sections tagged requires_jurisdiction_adaptation: true always route to a legal/linguistic reviewer, no exceptions, even for a one-word change.
Sections tagged direct_translation: true can go through MT + human post-edit for speed.
Every merged version gets a changelog entry and a last_legal_review date, so you can prove, in an audit, when each jurisdiction's version was last checked against local law.

Don't skip the distribution problem

Translating the policy correctly doesn't help if employees in Angola are still getting the English PDF because HR's distribution list wasn't updated. If you're pushing policies through an internal portal or onboarding flow, tie locale to employee jurisdiction at the data model level:

SELECT employee_id, policy_version, jurisdiction_locale
FROM policy_acknowledgements
WHERE jurisdiction_locale != employee.jurisdiction_locale;

Run that query periodically. If it returns rows, someone received a policy in the wrong language, which is exactly the failure mode the legal frameworks are trying to prevent.

The takeaway

Legal teams decide what the policy needs to say in each jurisdiction. Engineering and content-ops decide how reliably that gets maintained, versioned, and delivered to the right person in the right language. If your org is scaling into new markets, it's worth building the pipeline before you have six jurisdictions and a spreadsheet nobody trusts. For the legal and compliance side of why this matters jurisdiction by jurisdiction, the original breakdown is worth reading: https://www.m21global.com/en/blog/translating-data-protection-policies-staff-jurisdictions/.

Building a Terminology Pipeline for EU Pay Transparency Compliance (Directive 2023/970)

Diogo Heleno — Fri, 06 Nov 2026 10:44:43 +0000

The problem isn't translation, it's version drift

If you work in internal tools, HR tech, or compliance engineering at a company with offices in more than one EU country, Directive 2023/970 is about to land on your backlog. Member states have until June 2026 to transpose it, and companies are already updating pay policies, progression criteria, and the transparency reports the directive mandates for employers with 100+ employees.

The legal and HR side of this is covered well in this piece on translation requirements under the directive. I want to focus on something adjacent: the actual technical problem of keeping multiple language versions of a legally binding document in sync over time, without relying on someone manually re-reading five PDFs every time a clause changes.

This is a version control problem wearing a compliance costume.

Why this breaks normal translation workflows

Most teams handle multilingual content with one of two approaches:

Ad hoc: someone exports a Word doc, sends it to a translator or a vendor, gets it back, pastes it into a wiki.
CMS-based: content lives in a headless CMS with locale fields, and translations sync through a translation management system (TMS).

Both break down for legal/compliance docs because:

Terminology must be identical across every instance, not just "close enough." A pay policy, an internal FAQ, and a transparency report might all reference "objective and gender-neutral criteria," and if one translator renders it differently in each document, you now have three legally inconsistent definitions of the same concept in the same language.
Changes need audit trails. If a labour inspectorate asks why the Portuguese version of a progression clause differs from the German one, "we don't know, a vendor updated it at some point" is not an acceptable answer.
There's no single source of truth document. The policy, the report, and internal comms are separate files that reference the same underlying definitions, but nothing enforces that programmatically.

A practical fix: treat terminology as a schema, not prose

The fix that scales is borrowed straight from software engineering: stop treating legal terms as free text and start treating them as controlled vocabulary with IDs.

Here's a minimal structure:

{
  "term_id": "gpg-001",
  "en": "gender pay gap",
  "definition_en": "Difference in average pay between genders",
  "translations": {
    "pt": "disparidade salarial de género",
    "fr": "écart de rémunération entre les sexes",
    "de": "geschlechtsspezifisches Lohngefälle",
    "es": "brecha salarial de género"
  },
  "legal_reference": "Directive (EU) 2023/970, Art. 3",
  "last_reviewed": "2025-01-15",
  "reviewed_by": "legal-team"
}

Every document that references "gender pay gap" pulls from gpg-001, not from a translator's independent judgment each time. You build this once as a glossary database (a spreadsheet works for small orgs, a proper TMS glossary feature works better) and every subsequent document, policy update, or report references term IDs instead of re-translating from scratch.

Where this fits in a document pipeline

If your org already uses a TMS (Phrase, Lokalise, Smartling, etc.), most support glossary enforcement during translation jobs. The workflow looks like:

Source document authored in the HQ language, with key terms tagged (either manually or via a simple regex pass against your glossary).
Glossary check runs before the job goes to translators. Flag any defined term in the source that isn't in the glossary yet, force a legal review before translation starts.
Translation job dispatched with glossary attached as a constraint, not a suggestion. Most TMS platforms will highlight glossary mismatches in the translator's editor.
QA pass compares translated term usage against the glossary programmatically. A basic version of this is just a script:

import re

def check_glossary_consistency(translated_text, glossary, lang):
    issues = []
    for term in glossary:
        expected = term["translations"].get(lang)
        if not expected:
            continue
        # crude check: does the expected term appear at all
        # when the source term context is present
        if term["en"].lower() in translated_text.lower():
            issues.append(f"Source term '{term['en']}' leaked untranslated")
    return issues

This won't catch nuanced legal errors (you still need a second linguist for that, which is exactly the review layer the source article describes for high-risk documents), but it catches the dumb, expensive mistakes: untranslated terms, inconsistent capitalization, or a term translated three different ways across three documents.

Legal sign-off recorded against the specific glossary version, not just the document version. This is the audit trail piece. If gpg-001 changes on 2025-06-01, you want to know which documents were generated against the old definition and need re-review.

Handling multi-jurisdiction deadlines

Since national transposition deadlines won't align perfectly across member states, you'll likely need to version documents by jurisdiction and date, not just by language. A simple convention:

/policies/pay-transparency/
  es/2026-03-01_v2.docx
  fr/2026-01-15_v1.docx
  de/2026-06-01_v1.docx
  pt/2026-02-01_v3.docx

Pair this with a changelog that references the glossary version used, and you have something an auditor or legal team can actually trace.

The takeaway

Translation quality for compliance documents isn't really a linguistics problem, it's a data consistency problem. If you're building or maintaining the internal tooling for HR, legal, or compliance content at a multi-country company, the highest-leverage thing you can do before June 2026 is set up a controlled glossary with IDs, version history, and automated consistency checks, before the volume of required documents (policies, reports, FAQs, internal comms) makes manual tracking impossible.

The legal review still needs to happen, and for documents with direct litigation exposure you still want a qualified second linguist checking the final text, as outlined in the source article on translation requirements for Directive 2023/970. But the infrastructure around that review is squarely an engineering problem, and it's one most compliance teams haven't built yet.

Building a Multilingual Regulatory Reporting Pipeline for Solvency II (SFCR) Documents

Diogo Heleno — Wed, 04 Nov 2026 10:09:36 +0000

The problem isn't just translation, it's data consistency across formats

If you work in insurtech or build internal tooling for a multinational insurer, you've probably run into some version of this problem: the same regulatory figures need to exist, consistently, in a narrative document (the SFCR), a set of structured quantitative templates (QRTs), and multiple language versions, all of which have to agree with each other down to the decimal point.

A related article from M21Global covers the linguistic and regulatory side of this well: why SFCR translation requires Solvency II expertise, not just language fluency. That's the compliance angle. This post is about the engineering angle: how do you actually build a pipeline that keeps terminology, figures and structure consistent across languages and report cycles, without relying on manual cross-checking every year?

Why this is a data problem before it's a translation problem

The SFCR mixes two very different content types:

Structured data: SCR/MCR ratios, eligible own funds, QRT templates with EIOPA-standardized row/column labels
Unstructured narrative: governance descriptions, risk profile commentary, valuation methodology text

Most teams treat the whole document as unstructured text and hand it to a translation vendor as a Word or InDesign file. That's how you get the exact bugs described in the source article: a term like "technical provisions" translated inconsistently in section 3 versus section 5, or a QRT label that doesn't match the officially published EIOPA translation for that language.

The fix isn't better proofreading. It's separating the structured and unstructured parts of the pipeline and treating terminology as a controlled vocabulary, not free text.

Step 1: Pull QRT labels from EIOPA's own taxonomy

EIOPA publishes the Solvency II reporting taxonomy (XBRL-based) with standardized labels in every official EU language. If your reporting system generates QRTs programmatically, you should be pulling labels directly from this taxonomy rather than letting a translator retype them.

A minimal approach:

# Pseudocode: resolve QRT labels from the EIOPA taxonomy
import requests

TAXONOMY_URL = "https://eiopa.europa.eu/taxonomy/2.x.x/labels.json"

def get_label(concept_id: str, lang: str) -> str:
    labels = requests.get(TAXONOMY_URL).json()
    return labels[concept_id].get(lang, labels[concept_id]["en"])

# Example
get_label("s2md_met:mi362", "fr")  # -> "Provisions techniques"

This guarantees your QRT labels match what the French or Spanish supervisor already expects to see, because it's the same source EIOPA uses. No translator discretion involved for this part.

Step 2: Treat narrative terminology as a glossary, not prose

For the narrative sections, build a termbase before translation starts, not after. Tools like SDL MultiTerm, Phrase TMS, or even a well-maintained spreadsheet synced to a CAT tool work fine. The key fields:

{
  "term_en": "loss-absorbing capacity of deferred taxes",
  "term_fr": "capacité d'absorption des pertes par les impôts différés",
  "term_es": "capacidad de absorción de pérdidas de los impuestos diferidos",
  "domain": "Solvency II - Pillar 1",
  "source": "EIOPA glossary v2.0",
  "do_not_translate_as": ["capacité d'absorption fiscale"]
}

If you're integrating with a translation API (DeepL API, Google Cloud Translation, Phrase), most support glossary injection. For example, with the DeepL API:

import deepl

translator = deepl.Translator("YOUR_API_KEY")

glossary = translator.create_glossary(
    "solvency-ii-fr",
    source_lang="EN",
    target_lang="FR",
    entries={
        "technical provisions": "provisions techniques",
        "own funds": "fonds propres",
        "SCR coverage ratio": "ratio de couverture du SCR"
    }
)

result = translator.translate_text(
    "The SCR coverage ratio remained above 150%.",
    source_lang="EN",
    target_lang="FR",
    glossary=glossary
)

This won't replace a qualified actuarial translator for the final narrative, but it catches the machine-translation baseline errors before a human reviewer even sees the draft, and it enforces consistency for terms that recur hundreds of times across a 100+ page group report.

Step 3: Version-control the translation memory, not just the document

SFCRs repeat heavily year over year: boilerplate governance descriptions, standard risk disclosures, methodology notes. If your translation memory (TM) lives inside a vendor's proprietary tool with no export discipline, you lose that leverage every renewal cycle.

Practical setup:

Export your TM as TMX after every cycle and store it in your document repo (or a dedicated bucket), tagged by reporting year and entity
Diff this year's source text against last year's before sending anything out for translation, so you're only paying for and reviewing genuinely new content
Run a terminology consistency check automatically using a tool like checkmate or a custom script that flags any term translated two different ways within the same document set

# crude but effective: flag inconsistent translations of a key term
grep -o "technical provisions" report_en.txt | wc -l
grep -o "provisions techniques" report_fr.txt | wc -l
grep -o "claims provisions" report_fr.txt  # should return nothing if mistranslated

Step 4: Build the cross-check between narrative and QRTs into CI

The most expensive failure mode is a narrative section that states one SCR ratio while the QRT annex states another, something that happens more often than you'd expect when narrative and quantitative teams work in parallel and translation touches both independently.

If your reporting pipeline already generates both outputs from a common data source (which it should), add a validation step that extracts key figures from both the translated narrative and the translated QRT and asserts they match:

def validate_consistency(narrative_text, qrt_data, lang):
    extracted_scr = extract_number_near(narrative_text, keyword_map[lang]["scr_ratio"])
    qrt_scr = qrt_data["scr_coverage_ratio"]
    assert abs(extracted_scr - qrt_scr) < 0.01, f"Mismatch in {lang}: {extracted_scr} vs {qrt_scr}"

This is a simple regex/NLP extraction problem, not magic, but almost nobody builds it because translation is treated as a separate workstream from the data pipeline. It shouldn't be.

Where this fits with external translation vendors

None of this replaces a qualified financial/insurance translator for the final narrative text. Regulatory language still needs a human who understands Solvency II, and a second reviewer for quality assurance, which is exactly the workflow described in the source article for sensitive compliance documents.

What this pipeline does is reduce the surface area of what needs human judgment, by making sure QRT labels, recurring terminology and cross-document figures are consistent and machine-verifiable before anyone's billing hours to proofread them. For a report that runs past a hundred pages per market across three or more jurisdictions, that's the difference between a predictable annual process and a scramble every filing deadline.

If you're responsible for the reporting infrastructure side of this rather than the compliance side, it's worth treating your SFCR cycle the same way you'd treat any other data pipeline with multiple consumers: single source of truth, automated validation, and version-controlled artifacts, language included.

Building a Multilingual Documentation Pipeline for EU Machinery Regulation 2023/1230

Diogo Heleno — Wed, 04 Nov 2026 07:03:39 +0000

Regulation (EU) 2023/1230 kicks in on 20 January 2027 and replaces the old Machinery Directive. If your company builds hardware that ships into the EU, this isn't just a legal department problem. Someone has to engineer the actual pipeline that takes a source manual and produces N compliant, synchronized, versioned translations, including documentation for AI-based safety components that didn't exist as a category under the old rules.

The legal background is covered well in this breakdown of the regulation. This post is about the other half of the problem: how do you actually build and maintain a system that keeps dozens of translated documents in sync with a source manual that keeps changing?

Why this is a content engineering problem, not just a translation problem

A single machine's documentation set usually includes:

User manual
Safety warnings and labels
EC declaration of conformity
Assembly / maintenance instructions
AI system behavior documentation (new requirement)

Multiply that by every target market language, and you get a matrix where a single engineering change (say, a new emergency stop procedure) has to propagate correctly into every cell. Do this manually with email attachments and shared drives, and you will eventually ship a French manual with an outdated safety procedure. That's not a hypothetical, it's the default failure mode of unmanaged documentation.

The fix is to treat your manuals the way you treat code: version-controlled source content, a defined build pipeline, and automated checks before anything gets published.

Structure source content so it's translatable by design

Before any translation tooling, your source documentation needs to be structured, not a monolithic Word doc or PDF. Options that work well:

DITA XML — purpose-built for technical documentation with reuse and conditional content
Markdown + a static site generator (e.g., Docusaurus, which has built-in i18n support)
Structured FrameMaker or Paligo if you're already in a DTP-heavy workflow

The goal is separating content from layout, and splitting documents into translatable segments that can be tracked individually. If a safety warning is a discrete, identifiable unit, you can diff it, flag it for retranslation, and verify it didn't silently change meaning across 8 language versions.

# Example: segment metadata for a safety warning block
id: safety-warning-estop-001
source_lang: en
criticality: high
last_updated: 2025-03-12
translations:
  es: { status: approved, translator: jsmith, reviewed: true }
  pt: { status: pending_review, translator: mcosta, reviewed: false }
  pl: { status: outdated, reason: source_changed }

This kind of metadata is what lets you build automated gates later.

Translation memory and terminology as infrastructure, not an afterthought

The source article points out that inconsistent terminology across translated machinery manuals ("residual risk" vs "remaining risk", "emergency stop" vs "panic button") is a recurring compliance risk. From an implementation standpoint, this is solved with two artifacts that should live in your repo alongside the content:

A termbase (TBX format is the standard) with approved terms per language, locked for safety-critical vocabulary
A translation memory (TM) in TMX format, shared across every translator and vendor touching the project

If you're using CAT tools (memoQ, Trados, or open-source options like OmegaT), both plug into these formats directly. The key engineering decision is: don't let terminology live in a vendor's proprietary silo. Export it, version it, and treat changes to the termbase as pull requests that need review, because a wrong approval here propagates into every future translation.

# Example: validating a translated segment against the termbase
python validate_terms.py \
  --source manual_en.xml \
  --target manual_es.xml \
  --termbase machinery_terms.tbx \
  --lang es

A simple script like this, run in CI, can flag when a translator used "protección genérica" instead of the approved "dispositivo de protección" for "safeguarding." It won't replace human QA, but it catches the cheap, high-frequency errors before they reach a reviewer.

Automating change detection and re-translation triggers

Under 2023/1230, any substantial modification to the machine requires updated documentation, in every translated version. This is a classic cache invalidation problem. You need:

A way to detect that source content changed (git diff on structured XML/Markdown is enough)
A way to map which translated segments are now stale
A workflow that routes stale segments to translators/reviewers automatically, instead of relying on someone remembering to notify the translation vendor

# Pseudocode: flag translations as outdated when source changes
for segment in source_segments:
    if segment.hash != last_known_hash[segment.id]:
        for lang, translation in segment.translations.items():
            translation.status = "outdated"
            notify_translation_queue(segment.id, lang)

This is the same pattern as invalidating a CDN cache after a deploy. The difference is the stakes: a stale safety instruction in Polish isn't a UX bug, it's a liability and compliance exposure.

CI checks before publishing a manual

Borrowing from software release practices, a documentation pipeline for regulated manuals should run automated checks before anything is marked ready for a notified body or market release:

Completeness check: every required language has a translation for every segment
Terminology check: approved terms used consistently (script above)
Placeholder/variable check: if the manual has dynamic fields (model number, voltage rating), verify they weren't mistranslated or dropped
Layout check: safety icons and warning placement preserved (this is why desktop publishing matters as much as the text itself)
Sign-off check: high-criticality segments have a recorded second-linguist review, not just machine translation post-editing

A minimal CI config might look like:

# .github/workflows/docs-compliance.yml
name: docs-compliance
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python check_completeness.py --langs es,pt,pl,de,fr
      - run: python validate_terms.py --termbase machinery_terms.tbx
      - run: python check_critical_signoff.py --criticality high

Failing this pipeline should block publication the same way a failing test suite blocks a merge.

Where to draw the line between automation and human review

Machine translation plus post-editing is fine for descriptive content, parts catalogues, FAQs, general operating notes. It is not fine, on its own, for safety warnings, the declaration of conformity, or AI system behavior documentation, where a second human reviewer is the only thing standing between an ambiguous sentence and a market surveillance finding. Build your pipeline so criticality is a first-class metadata field, not something decided ad hoc per document.

The regulatory deadline is 2027, but the pipeline work, structuring content, building termbases, wiring up CI checks, takes longer to get right than most teams expect. Start building the infrastructure now, even if your first few manuals still go through a mostly manual process.

Building a Document Validation Pipeline for Cross-Border Bureaucracy (Vehicle Import Case Study)

Diogo Heleno — Tue, 03 Nov 2026 07:06:12 +0000

Most of us never think about bureaucratic document workflows until we're stuck in one. Importing a car into Portugal is a good case study because it exposes a pattern that shows up everywhere in compliance-heavy software: data that is technically correct but administratively invalid.

The source article from M21Global (certified translation for IMT vehicle registration) breaks down the legal side well: which documents need certified translation, why a sworn translation from Germany or Spain doesn't automatically count in Portugal, and when an apostille is actually required. I want to look at the same problem from a different angle: if you were building a system (internal tool, SaaS product, or just a personal script) to track and validate this kind of document chain, what would the data model and validation rules actually look like?

This applies beyond cars. Any workflow involving foreign-issued legal documents, government agencies, and translation requirements hits the same structural problems.

The core problem: validity isn't binary

A document in this context has at least three independent states:

Linguistic validity: is it in a language the receiving authority accepts?
Translation validity: if translated, was it certified by an authority the receiving country recognizes?
Authenticity validity: does the receiving country need extra proof the original document is real (apostille/legalisation)?

The mistake most naive systems (and most people) make is treating "translated" as a single boolean flag. It isn't. A translation can exist and still be worthless for a given jurisdiction, because the certifying authority doesn't match what the destination requires.

Modeling this properly

Here's a rough schema for tracking documents through a cross-border bureaucratic process:

from dataclasses import dataclass
from enum import Enum
from datetime import date

class CertificationAuthority(Enum):
    SWORN_TRANSLATOR = "sworn_translator"      # e.g. Germany, Spain
    LAWYER_NOTARY = "lawyer_notary"             # e.g. Portugal
    NONE = "none"

class AuthenticationType(Enum):
    APOSTILLE = "apostille"
    CONSULAR_LEGALISATION = "consular_legalisation"
    NOT_REQUIRED = "not_required"

@dataclass
class Document:
    doc_type: str                 # "registration_certificate", "invoice", "coc", etc.
    origin_country: str
    origin_language: str
    issued_date: date

@dataclass
class TranslationRecord:
    document: Document
    target_language: str
    certifying_authority: CertificationAuthority
    certifying_country: str
    translator_credential_id: str | None

@dataclass
class DestinationRequirement:
    destination_country: str
    doc_type: str
    accepted_certification: list[CertificationAuthority]
    authentication_required: AuthenticationType

The key relationship to validate is: does TranslationRecord.certifying_authority intersect with DestinationRequirement.accepted_certification?

In the Portugal/IMT case, the answer is almost always "only LAWYER_NOTARY counts," regardless of where the translation happened. A SWORN_TRANSLATOR certification from Germany fails this check even though it's a perfectly valid certification in its own country. This is exactly the kind of cross-jurisdiction mismatch that trips up both manual processes and automated ones if you hardcode assumptions like "translated = valid."

A simple validation function

def is_translation_accepted(record: TranslationRecord, req: DestinationRequirement) -> bool:
    if record.document.doc_type != req.doc_type:
        raise ValueError("Mismatched document type")
    return record.certifying_authority in req.accepted_certification

def needs_authentication(document: Document, req: DestinationRequirement) -> bool:
    return req.authentication_required != AuthenticationType.NOT_REQUIRED

This looks trivial, but the value isn't the code, it's forcing the requirements into an explicit, queryable structure instead of leaving them as institutional knowledge scattered across PDFs and agency phone calls. If you're building an internal tool for a customs agency, dealership network, or translation company that processes many of these files, this structure scales a lot better than a checklist in a spreadsheet.

Where automation actually helps (and where it doesn't)

This is a good moment to be honest about limits. You can automate:

Flagging which documents require translation based on detected language (basic language detection via langdetect or fasttext is enough for a first pass)
Cross-checking VIN numbers between original and translated documents with regex and a checksum validator (VINs have a known check-digit algorithm, ISO 3779)
Tracking certification metadata and flagging mismatches like the Germany/Portugal example above
Generating a checklist per vehicle origin country, pulled from a rules table your team maintains

You cannot automate:

Producing the actual certified translation (this requires a licensed lawyer or notary under Portuguese rules, not a model or API)
Guaranteeing a translation agency's certificate format will be accepted, since this is ultimately a judgment call by the receiving institution
Replacing the final human review that catches terminology mismatches (the article mentions misclassified fuel types and vehicle categories as a common rejection cause, and that's a domain-glossary problem, not a translation-engine problem)

VIN mismatch detection

Since mismatched VINs between original and translated documents are called out as a top rejection reason, here's a minimal check-digit validator worth having in your toolkit if you're processing these documents in bulk:

TRANSLITERATION = {**{c: v for c, v in zip("ABCDEFGHJKLMNPRSTUVWXYZ", 
    [1,2,3,4,5,6,7,8,1,2,3,4,5,7,9,2,3,4,5,6,7,8,9])}}
WEIGHTS = [8,7,6,5,4,3,2,10,0,9,8,7,6,5,4,3,2]

def vin_check_digit(vin: str) -> str:
    total = 0
    for char, weight in zip(vin, WEIGHTS):
        value = int(char) if char.isdigit() else TRANSLITERATION.get(char, 0)
        total += value * weight
    remainder = total % 11
    return "X" if remainder == 10 else str(remainder)

def vins_match(original: str, translated: str) -> bool:
    return original.upper().strip() == translated.upper().strip()

Run this as a pre-submission check before a file goes to the IMT or any similar authority, and you catch transcription errors before they cost you a rejected application and another translation request.

Takeaway

The legal and procedural details (which authority certifies what, when an apostille applies) are jurisdiction-specific and genuinely require expert review, which is the ground the original M21Global article covers well. But the underlying data problem, matching document states against destination requirements across incompatible certification systems, is a general software problem you can model, validate, and partially automate. If you're building tooling for an agency that handles a volume of these, treat "certification authority" and "destination requirement" as first-class entities instead of a free-text field, and you'll save yourself a lot of rejected filings.