DEV Community: Diogo Heleno

Building a Document Pipeline for International University Applications (Apostilles, Translations, and Deadlines)

Diogo Heleno — Fri, 23 Oct 2026 06:01:01 +0000

If you've ever helped someone apply to a university abroad, or gone through it yourself, you know the paperwork is basically a small distributed systems problem. You have documents with dependencies (apostille before translation), hard deadlines, multiple stakeholders (issuing institution, apostille authority, translation vendor, admissions office), and no retries once a deadline passes.

The source article from M21Global covers the certification requirements for academic transcripts in good detail: what a certified translation is, which countries require what, and why the apostille-then-translate order matters. That's useful if you're the applicant. This post is for the other case: you're helping a partner, sibling, friend, or you're building a tool for a cohort of applicants (international student advisors do this a lot), and you want to treat the process like what it actually is — a workflow with state, deadlines, and failure modes.

Model it as a pipeline, not a checklist

The natural instinct is to make a checklist. Don't. A checklist hides the dependency graph. What you actually have is a DAG:

issuing institution ---> original document
original document ---> apostille (if required)
apostille (or original) ---> certified translation
certified translation ---> submission package
submission package ---> university deadline

The critical insight from the source article — apostille before translation — is really just topological sorting. If you translate before the apostille is applied, you've broken the dependency order and have to redo work. This is the same class of bug as deploying a service before its config is in place.

If you're tracking this for more than one applicant (say you're a university counselor, an immigration consultant, or building an internal tool), model each document as a state machine:

from enum import Enum, auto

class DocState(Enum):
    NOT_REQUESTED = auto()
    REQUESTED = auto()
    RECEIVED = auto()
    APOSTILLE_PENDING = auto()
    APOSTILLED = auto()
    TRANSLATION_PENDING = auto()
    TRANSLATED = auto()
    READY_FOR_SUBMISSION = auto()

TRANSITIONS = {
    DocState.NOT_REQUESTED: [DocState.REQUESTED],
    DocState.REQUESTED: [DocState.RECEIVED],
    DocState.RECEIVED: [DocState.APOSTILLE_PENDING, DocState.TRANSLATION_PENDING],
    DocState.APOSTILLE_PENDING: [DocState.APOSTILLED],
    DocState.APOSTILLED: [DocState.TRANSLATION_PENDING],
    DocState.TRANSLATION_PENDING: [DocState.TRANSLATED],
    DocState.TRANSLATED: [DocState.READY_FOR_SUBMISSION]}

This looks like overkill for one person's grad school application. It stops being overkill the moment you're tracking transcripts, diplomas, diploma supplements, and recommendation letters across three universities with three different requirement sets, which is the normal case, not the edge case.

Deadline math: work backward, not forward

The source article mentions starting eight weeks before a January or March deadline. That number isn't arbitrary, it's a sum of lead times that vary by country and document type. Don't hardcode "8 weeks" as a rule, hardcode the components and compute it:

from datetime import date, timedelta

LEAD_TIMES = {
    "request_transcript": 10,      # business days, institution-dependent
    "apostille_processing": 10,    # varies wildly by country/authority
    "certified_translation": 5,    # standard service level
    "certified_translation_reviewed": 10,  # multi-reviewer / ISO-audited service
    "buffer": 5,                   # for the inevitable resubmission
}

def latest_start_date(deadline: date, needs_apostille: bool, needs_review_tier: bool) -> date:
    total_days = LEAD_TIMES["request_transcript"]
    if needs_apostille:
        total_days += LEAD_TIMES["apostille_processing"]
    total_days += (
        LEAD_TIMES["certified_translation_reviewed"]
        if needs_review_tier
        else LEAD_TIMES["certified_translation"]
    )
    total_days += LEAD_TIMES["buffer"]
    return deadline - timedelta(days=total_days)

Run this per document, per destination country, and take the earliest resulting date across all documents. That's your actual "start now" date. For a German application requiring a sworn translator through Uni-assist plus an apostille, you'll often land well past the generic "8 weeks" guidance. For a UK application with no apostille requirement, you might have more slack than you think.

Requirements differ by country: treat it as config, not logic

The source article lists requirements for the UK, Germany, US/Canada, and the Netherlands. The important engineering takeaway isn't the specific rules, it's that these rules change per institution and change over time (Uni-assist updates its specs, WES updates its format requirements). Don't bake these into conditional logic scattered through your process. Keep them as data:

destinations:
  germany:
    apostille_required: false  # Portugal + Germany, EU context
    sworn_translator_required: true
    intermediary: uni-assist
    notes: "Check uni-assist specs before ordering, they change"
  united_kingdom:
    apostille_required: false
    sworn_translator_required: false
    intermediary: ucas
  united_states:
    apostille_required: varies
    credential_evaluation: WES
    notes: "Some programs require direct submission from issuing institution"
  netherlands:
    apostille_required: false
    sworn_translator_required: false

This structure makes it trivial to add a destination, update a rule when an institution changes its process, or generate a per-applicant checklist programmatically. If you're building something for an advising office, this is also your audit trail: when a requirement changes, you have a diff.

Translation quality tiers are a real engineering tradeoff

One detail in the source article is worth calling out from a QA perspective: for high-stakes documents like transcripts, a single-translator pass isn't the same guarantee as a translate-review-QA pipeline (the article describes a three-person process audited under ISO 17100:2015). This maps directly to code review practices. A transcript with a mistranscribed grade or a mismatched course title is a silent data-corruption bug, it won't throw an error, it'll just cause an incorrect academic evaluation downstream. For documents like this, paying for the reviewed tier is the equivalent of requiring two approvals on a production deploy instead of one.

Practical takeaways

Model document dependencies explicitly. Apostille-before-translation isn't a tip, it's a topological constraint.
Compute deadlines backward from lead times, don't guess a round number.
Store per-country requirements as data you can update, not logic you have to refactor.
Treat translation quality tier as a risk decision proportional to the document's stakes, same as you would for test coverage or review requirements on critical code paths.

None of this requires you to build actual software; a spreadsheet with these principles encoded works fine for a single applicant. But if you're supporting more than one person through this process, or doing it repeatedly, the pipeline framing saves you from the failure mode the source article describes: finding out about a missing certification three weeks before a deadline, when there's no time left to fix it.

Building a Document Pipeline for Multi-Jurisdiction Legal Contracts (Shareholders' Agreements, Apostilles, and Terminology Drift)

Diogo Heleno — Thu, 22 Oct 2026 11:13:18 +0000

Why this is a data problem, not just a legal one

If you've ever worked on a legaltech product, cap table platform, or internal tooling for an M&A team, you've probably run into this: a shareholders' agreement needs to exist in two or more languages, and those versions have to be legally equivalent, not just linguistically similar.

The source article on shareholders' agreement translation for foreign investors covers the legal side well: why terms like "drag-along", "tag-along" or "liquidation preference" don't map cleanly across legal systems, and when you need certified translation versus an apostille versus consular legalisation.

What that article doesn't get into, and what's actually relevant if you're building tools around this process, is how you structure a pipeline that handles multilingual legal documents without losing track of which clause maps to which jurisdiction, which version is authoritative, and which terminology decisions were made and why.

This is squarely a document management and terminology consistency problem. Let's break down how to approach it technically.

The core challenge: terminology isn't 1:1

Standard translation APIs (Google Cloud Translation, DeepL API, Azure Translator) are built on the assumption that a term in language A has a reasonably stable equivalent in language B. Legal terminology breaks that assumption constantly.

"Shareholders' agreement" and "acordo parassocial" don't cover identical scope in every jurisdiction. "Vesting" or "cliff period" may not have a single fixed Portuguese equivalent at all. If you naively run a 40-page contract through a generic MT engine, you'll get fluent Portuguese that is quietly wrong in ways a non-lawyer reviewer won't catch.

If you're building or integrating translation tooling for legal documents, don't treat this as a translation problem. Treat it as a controlled vocabulary problem.

Practical approach: terminology databases over raw MT

Most serious CAT tools (SDL Trados, memoQ, Smartcat) support termbases — structured glossaries that get enforced during translation, whether human or machine-assisted. If you're building something custom:

# Simplified example: enforcing a legal termbase before/after MT pass
import json

with open("legal_termbase_en_pt.json") as f:
    termbase = json.load(f)
# termbase = {"drag-along right": "direito de arrastamento", ...}

def flag_unmapped_terms(source_text, termbase):
    flagged = []
    for term in termbase:
        if term.lower() in source_text.lower():
            flagged.append(term)
    return flagged

def enforce_termbase(mt_output, source_text, termbase):
    issues = []
    for term, approved_translation in termbase.items():
        if term.lower() in source_text.lower():
            if approved_translation not in mt_output:
                issues.append((term, approved_translation))
    return issues

This won't replace a qualified legal translator, but it gives you an automated first-pass QA layer: anywhere the source contains a term from your controlled vocabulary and the output doesn't contain the approved equivalent, you flag it for human review instead of letting it slip through silently.

The real engineering work is building and maintaining that termbase per jurisdiction pair (PT-EN for UK/US investors, PT-DE, PT-FR, PT-AO for Angola, etc.), since, as the source article points out, even Portuguese-speaking jurisdictions diverge on substantive points like share transfer rules.

Versioning: treat contract translations like code

A shareholders' agreement under negotiation goes through redlines. Each redline on the source language needs to propagate to every translated version, and you need an audit trail of which translated clause corresponds to which source revision.

This maps surprisingly well to standard version control concepts:

Store each language version as a separate file in the same repo, aligned by clause ID, not by line number (contract clauses get renumbered constantly).
Use a structured format (XML, or even a constrained Markdown with clause anchors) instead of raw .docx, so diffs are meaningful.
Tag releases at the point a version is sent for certified translation or apostille, so you can always answer "which exact text was certified".

<clause id="cl-14-drag-along" status="certified" lang="pt" source-rev="v12">
  <text>O acionista maioritário pode exercer o direito de arrastamento...</text>
</clause>

If your org handles more than a handful of these a year, this structure is worth building even as a thin layer on top of Git, with clause-level metadata tracked separately from prose.

Automating the certification/apostille decision tree

The source article lays out a genuinely useful decision tree:

Document stays in Portugal → certified translation via a lawyer or notary (no "sworn translator" concept in Portugal)
Document used in a Hague Convention country → apostille via PGR
Document used in a non-Convention country (e.g. Angola) → consular legalisation via Ministério dos Negócios Estrangeiros + destination embassy
Document used in Brazil, Spain, France, Germany → destination country's own sworn/certified translator regime applies

This is a clean candidate for a small rules engine rather than a wiki page someone has to remember to check:

HAGUE_COUNTRIES = {"US", "UK", "DE", "FR", "ES", ...}  # populate from official list
NON_HAGUE = {"AO"}  # Angola, etc.

def required_authentication(destination_country, origin="PT"):
    if destination_country == origin:
        return "certified_translation_only"
    if destination_country in HAGUE_COUNTRIES:
        return "certified_translation_plus_apostille"
    if destination_country in NON_HAGUE:
        return "consular_legalisation"
    if destination_country in {"BR", "ES", "FR", "DE"}:
        return "destination_sworn_translator_regime"
    return "manual_review_required"

This is trivial code, but encoding it means your legal ops team (or your SaaS product, if you're building for legal/compliance) stops relying on institutional memory for a decision that has real consequences if gotten wrong. Keep the underlying lists in a config file that gets reviewed quarterly, these rules do change.

Where human review still has to sit in the loop

None of the above replaces qualified legal translators. The source article mentions a workflow with three linguists (translator, editor, QC reviewer) under ISO 17100, which is the right instinct: high-stakes legal documents need redundant human review, not just better tooling.

What the tooling buys you is:

Catching terminology drift before it reaches a human reviewer, so their time goes to judgment calls, not typo-hunting
A reliable audit trail of which version was certified, apostilled, or legalised, and when
A repeatable, testable decision process for the certification/apostille/legalisation question, instead of re-deriving it on every deal

If you're building internal tooling for a legal, compliance, or corporate development team that handles cross-border contracts regularly, this is a reasonable architecture to start from. If you're handling a one-off shareholders' agreement for an actual deal, skip the tooling and go straight to a legal translation provider with a documented ISO 17100 process, the stakes are too high for a DIY pipeline on a single contract.

Building a Document Requirements Checklist API for International Legal Workflows

Diogo Heleno — Tue, 20 Oct 2026 06:03:29 +0000

The problem: requirements live in people's heads, not in systems

If you've ever worked on an internal tool for legal ops, HR, or compliance teams, you've probably run into this pattern: someone orders a certified translation, a notarization, or an apostille, and weeks later it bounces back because a receiving authority had a formatting requirement nobody captured anywhere.

There's a good write-up on the human side of this problem in this article on certified translation rejections. The short version: certification standards vary wildly by country and even by institution, and the fix has to happen before the document is produced, not after rejection.

That's a workflow problem, and workflow problems are things we can actually model in software. This post walks through how to think about building a lightweight requirements-checklist system for document localization and certification pipelines, something you could bolt onto an internal tool, a client portal, or a document management system.

Why this isn't just a static form

The naive approach is a dropdown: "select destination country" then show a static list of requirements. That breaks almost immediately because requirements aren't purely country-level. They depend on:

Destination country (Portugal vs Brazil vs Angola have fundamentally different certification models)
Receiving institution type (court, university, notary, HR department)
Document type (articles of association vs birth certificate vs contract)
Hague Apostille Convention membership of the destination country
Direction of travel (document originating in Portugal going to Angola is a different legalisation chain than the reverse)

That's a multi-dimensional lookup, which means your data model needs to be a decision tree or rules engine, not a flat table.

A simple rules-based data model

Here's a minimal schema that captures the logic described in the source article:

{
  "country": "AO",
  "name": "Angola",
  "hagueMember": false,
  "swornTranslatorRegistry": false,
  "certificationModel": "notary-authenticated",
  "legalisationChain": {
    "inbound": [
      "origin_country_mfa_authentication",
      "angolan_consulate_legalisation"
    ],
    "outbound": [
      "mirex_legalisation"
    ]
  },
  "certificateValidityMonths": null
}

And for a Hague member country:

{
  "country": "PT",
  "name": "Portugal",
  "hagueMember": true,
  "swornTranslatorRegistry": false,
  "certificationModel": "lawyer-or-notary-attested",
  "apostilleIssuer": "PGR",
  "certificateValidityMonths": 6
}

The key fields that actually drive decisions are hagueMember (apostille vs consular legalisation), swornTranslatorRegistry (whether a local sworn translator is mandatory), and legalisationChain.inbound vs .outbound, since the direction matters a lot, as the source article points out with the MIREX example (it only legalises outbound Angolan documents, never inbound foreign ones).

A basic resolver function

Once you have the data modeled, the logic to generate a checklist is mostly conditionals:

function resolveRequirements({ originCountry, destCountry, direction, documentType }) {
  const dest = countryRules[destCountry];
  const origin = countryRules[originCountry];
  const checklist = [];

  if (dest.swornTranslatorRegistry) {
    checklist.push({
      type: "warning",
      message: `${dest.name} maintains a sworn translator registry. Confirm whether a translation certified in ${origin.name} is accepted, or if a locally sworn translator is required.`
    });
  }

  if (dest.hagueMember) {
    checklist.push({
      type: "action",
      message: `Apostille required (Hague Convention). Confirm whether it applies to the original, the translation, or both.`
    });
  } else {
    const chain = dest.legalisationChain[direction] || [];
    checklist.push({
      type: "action",
      message: `${dest.name} is not a Hague signatory. Legalisation chain: ${chain.join(" -> ")}`
    });
  }

  if (dest.certificateValidityMonths) {
    checklist.push({
      type: "info",
      message: `Certificate must be issued within ${dest.certificateValidityMonths} months of submission.`
    });
  }

  checklist.push({
    type: "action",
    message: "Get the above confirmed in writing (email) from the receiving authority before ordering translation."
  });

  return checklist;
}

This is deliberately simple. The point isn't to build a legal advice engine, it's to force the right questions to surface before anyone places an order. That last line in the checklist matters as much as the logic: the system's job is to generate the questions to ask, not to pretend it has authoritative legal answers. Requirements change, authorities are inconsistent, and a resolver like this needs a disclaimer baked into the UI, not just the code comment.

Where this fits in a real pipeline

If you're building internal tooling for a company that regularly deals with cross-border documents (legal ops, immigration, HR for expats, procurement with international vendors), this kind of checklist generator slots in naturally as:

A pre-flight step in a document request form, before it ever reaches a vendor
A validation gate in a DMS workflow, blocking submission until checklist items are marked "confirmed with authority"
An audit trail generator, since the source article's advice to "get confirmation in writing" is exactly the kind of thing you want timestamped and stored, not left in someone's inbox

A practical addition: log each confirmed requirement with a timestamp and source (email, portal screenshot, phone log reference). When a document gets rejected six months later, you want to pull up exactly what was confirmed and when, not reconstruct it from memory.

function logConfirmation(checklistItemId, { confirmedBy, source, date, notes }) {
  return db.confirmations.insert({
    checklistItemId,
    confirmedBy,
    source,
    date,
    notes,
    createdAt: new Date().toISOString()
  });
}

Maintaining the rules table

The hard part isn't the code, it's keeping the underlying rules accurate. Apostille Convention membership changes (several countries have joined in the past decade), and institutional requirements shift without much public notice.

Practical approach:

Treat the country rules table as data, not code, so non-engineers (legal ops, compliance) can update it
Version it and require sign-off on changes, since a wrong entry here causes real-world rejections
Add a lastVerified date field per country and flag entries older than, say, 12 months for review
Link each rule to a source document or email confirmation where possible

Takeaway

Rejected certified translations are rarely a quality problem, they're a missing-checklist problem. If your org handles this kind of document flow more than a handful of times a year, it's worth treating the "ask the receiving authority first" step as a structured, loggable part of the pipeline instead of tribal knowledge. The rules engine doesn't need to be sophisticated. It just needs to make the right questions impossible to skip.

Parsing and Validating Bank Statements for Visa Applications: A Technical Checklist

Diogo Heleno — Mon, 19 Oct 2026 10:27:38 +0000

If you've ever built a document processing pipeline, you know bank statements are one of the messiest input formats out there. Every institution has its own layout, date format, decimal convention, and terminology. Now add a translation requirement on top, and you have a problem that looks a lot like data validation with legal consequences.

This post is for developers who are either building tools to help with immigration document prep (think: visa application assistants, document checklists, or OCR pipelines) or who are going through this process themselves and want to apply some engineering rigor to it. The original article on certified translation for D7 visa bank statements covers the legal and procedural side well. Here I want to dig into the technical failure modes that actually cause delays, because most of them are data formatting bugs in disguise.

The core problem: locale mismatches in financial documents

If you've worked with Intl.NumberFormat or moment.js locales, you already know the classic traps:

03/04/2024 means March 4th in the US and April 3rd almost everywhere else
1,234.56 in the US is 1.234,56 in Portugal, Germany, and most of the EU
Currency symbols placed before or after the amount change parsing logic

These aren't edge cases in a bank statement, they're the entire document. A single mis-parsed date on a deposit can make it look like income arrived outside the required window, which is exactly the kind of thing that triggers a clarification request from an immigration authority.

If you're building any kind of document-checking tool, treat every date and number field as untrusted input and validate against the source locale before any transformation:

from babel.dates import parse_date
from babel.numbers import parse_decimal

# Explicit locale, never guess
date_value = parse_date("03/04/2024", locale='en_US')
amount = parse_decimal("1,234.56", locale='en_US')

print(date_value, amount)

The moment you hardcode a locale assumption ("all our users are American" or "all documents are European") you've introduced a bug that only shows up when someone's visa application gets flagged.

Treat the document as structured data, not plain text

A common mistake described in the source article is translating a bank statement like it's a paragraph of prose, losing table alignment, headers, and footers in the process. This maps directly to a problem developers hit when doing OCR or PDF extraction: tables degrade badly when you flatten them to plain text.

If you're building or evaluating a tool to pre-process these documents (for OCR, translation memory, or review), prefer extraction methods that preserve layout:

import pdfplumber

with pdfplumber.open("bank_statement.pdf") as pdf:
    page = pdf.pages[0]
    table = page.extract_table()
    for row in table:
        print(row)

This keeps column structure intact, which matters because a certified translation is expected to mirror the original layout so a reviewer can compare line by line. If your pipeline flattens a table into a wall of text before handing it to a translator, you're creating rework downstream, whether that translator is a person or an LLM.

Building a pre-submission validation checklist

Whether you're a developer automating part of this process or just trying to keep your own application organized, a simple validation script catches most of the errors that cause delays. Something like:

REQUIRED_FIELDS = [
    "account_holder_name",
    "bank_name",
    "iban_or_account_number",
    "statement_period_start",
    "statement_period_end",
    "swift_bic",
]

def validate_statement(doc_fields: dict, required=REQUIRED_FIELDS):
    missing = [f for f in required if not doc_fields.get(f)]
    return missing

result = validate_statement({
    "account_holder_name": "Jane Doe",
    "bank_name": "Example Bank",
    "iban_or_account_number": None,
    "statement_period_start": "2024-01-01",
    "statement_period_end": "2024-01-31",
    "swift_bic": "EXAMPLUS",
})

if result:
    print(f"Missing required fields: {result}")

Run something like this across every document before it goes to translation. It won't catch translation quality issues, but it catches the structural ones: missing SWIFT/IBAN codes, incomplete statement periods, name mismatches across documents. These are exactly the issues the source article flags as common causes of delay, and they're trivial to automate checks for.

Name consistency across documents

One subtle issue: applicants often have slightly different name formatting across their bank statement, tax declaration, and passport (middle names included or dropped, diacritics normalized differently, order of surnames). This is a known problem in identity matching systems, and the same fuzzy-matching techniques apply here.

from rapidfuzz import fuzz

name_a = "Maria da Silva Santos"
name_b = "Maria Silva Santos"

score = fuzz.token_sort_ratio(name_a, name_b)
print(score)  # flag anything below ~90 for manual review

If you're building a document intake tool for this use case, running every name field through a similarity check against the applicant's passport name is a cheap way to flag inconsistencies before submission rather than after a rejection.

Where automation should stop

It's worth being clear about the limits here. Certified translation in Portugal has a legal requirement: a professional translator's work authenticated by a lawyer registered with the Ordem dos Advogados, or a notary. No amount of tooling replaces that step, and machine translation output, however fluent, doesn't meet the certification requirement AIMA expects.

What automation can do is reduce the number of round trips between you and the certified translator by making sure the source documents are complete, consistent, and correctly parsed before they ever reach a human translator's desk. That's a pure data quality problem, and it's one most of us have tools for already.

Takeaway

If you're dealing with this process yourself, or building tooling for others who are, treat bank statements like any other messy real-world data source: validate locale assumptions explicitly, preserve structure during extraction, and run consistency checks across the full document set before anything gets sent off for certified translation. It won't replace the legal step, but it will cut down on the back-and-forth that turns a three-week process into a three-month one.

Building a Terminology Pipeline for Multilingual Technical Documentation (Railway Case Study)

Diogo Heleno — Sun, 18 Oct 2026 06:03:35 +0000

Railway interoperability in the EU runs on documentation that has to be correct in every target language, every time. A mistranslated term in a safety case or an EC verification declaration isn't a typo you fix in the next release. It can invalidate a certification, trigger a non-conformity in an audit, or create liability nobody budgeted for.

A good breakdown of the regulatory side of this (Directive 2016/797/EU, TSIs, the role of Notified Bodies) is covered in this article on railway documentation translation. That piece focuses on the compliance and vendor-selection angle. This one is for the people who actually have to build and maintain the documentation pipeline: how do you manage multilingual technical content at scale without it becoming a terminology mess?

The problem generalizes well beyond rail. Anyone shipping regulated technical documentation (medical devices, industrial machinery, aerospace, automotive functional safety) deals with the same core issue: standardized terms, multiple languages, long document lifecycles, and zero tolerance for drift between versions.

The Core Problem: Terminology Drift Across Versions and Languages

Standards like EN 50126, EN 50128 and EN 50129 define precise vocabulary — failure mode, hazard log, safety integrity level, vital function. These aren't casual phrases; they map to specific concepts in a formal safety framework. If your German translation uses one term for "hazard" in version 1.0 of a safety plan and a slightly different term in version 1.3, you've introduced ambiguity into a document that auditors will read line by line.

This is a data consistency problem as much as a linguistic one. If you're building or buying a documentation pipeline, treat terminology like you'd treat a shared schema across microservices: single source of truth, versioned, and validated on every change.

Translation Memory and Termbases Aren't Optional Here

Most technical translation workflows rely on two structured assets:

Translation Memory (TM): a database of previously translated segments (sentence or paragraph level), reused automatically when the same or similar text reappears.
Termbase (TB): a controlled glossary mapping approved terms across all target languages, often with context notes and forbidden synonyms.

If you're integrating with a CAT (computer-assisted translation) tool or an LSP's workflow, these are usually exchanged as standard file formats:

.tmx   — Translation Memory eXchange (TM data)
.tbx   — TermBase eXchange (terminology data)
.xliff — bilingual file format for translation jobs

If your documentation is generated from structured sources (DITA, Markdown, DocBook, or even structured Word templates), you want your pipeline to export to XLIFF directly rather than hand-copying text into a translation portal. Most serious translation management systems (TMS) — memoQ, Phrase, Trados GroupShare — expose APIs for exactly this.

A Minimal CI-Style Pipeline for Regulated Technical Docs

Here's a pattern that works reasonably well for teams maintaining versioned technical documentation across languages:

1. Source doc authored/updated (Markdown/DITA/XML)
2. Extract translatable segments -> XLIFF
3. Push XLIFF to TMS via API (new job per changed segment)
4. TMS applies TM matches + flags terminology conflicts against TB
5. Human translator/reviewer resolves flags
6. Approved segments merged back into localized doc build
7. CI step diffs terminology usage against approved termbase
8. Fail build if unapproved term variants are introduced

Step 7 and 8 are the part most teams skip, and it's the part that actually prevents the EN 50128-style terminology violations mentioned in the source article. A simple script comparing extracted terms against your termbase catches a lot before it reaches a reviewer:

import re

def check_terms(doc_text, termbase):
    violations = []
    for canonical, forbidden_variants in termbase.items():
        for variant in forbidden_variants:
            if re.search(rf"\b{variant}\b", doc_text, re.IGNORECASE):
                violations.append((variant, canonical))
    return violations

termbase = {
    "hazard log": ["risk log", "danger log"],
    "safety integrity level": ["safety level", "integrity level"]}

violations = check_terms(localized_text, termbase)
if violations:
    raise SystemExit(f"Terminology violations found: {violations}")

This is trivial, but running it as a CI gate on every localized build is what separates ad hoc translation from a managed terminology process. Scale it with real NLP matching (lemmatization, fuzzy matching) if you're dealing with inflected languages like German or Spanish, where exact string matches won't catch everything.

Versioning Translation Memory Alongside Your Docs

Treat your TM and TB like code:

Store .tbx termbase files in the same repo as your documentation source, not in a translator's local CAT tool.
Tag TM snapshots to document releases (tm-v2.3-en-de.tmx), so you can reproduce exactly which translations were approved for a given certification submission.
Review termbase changes via pull request. A new approved term should go through the same scrutiny as a schema migration, because in safety documentation, it effectively is one.

This matters more than it sounds for audits. If a Notified Body asks why a term changed between document revisions, "here's the PR and the reviewer sign-off" is a much better answer than "the translator used a different word this time."

Where Human Review Still Has to Be in the Loop

None of this replaces qualified human translators, especially for safety-critical content. Machine translation and TM fuzzy-matching speed up throughput, but FMEA reports, hazard logs and safety cases require someone who understands the logical structure of the document, not just the vocabulary. The pipeline above is about making sure human review time is spent on genuinely ambiguous cases instead of catching the same terminology inconsistency for the fifth time.

If you're evaluating external translation providers for this kind of work, ISO 17100 certification and documented terminology management are the two things worth actually verifying, not just claimed in a sales page. The source article goes deeper into what to look for when selecting a provider for railway-specific projects.

Takeaway

If you're responsible for multilingual technical documentation in any regulated industry, the engineering problem is identical to any other system where consistency matters more than speed: version your terminology, automate the boring consistency checks, and keep human expertise focused on the parts that actually require judgment.

Building a Document Pipeline for International Job Applications (OCR, Validation, and Translation Tracking)

Diogo Heleno — Tue, 13 Oct 2026 06:03:35 +0000

If you've ever helped a friend, partner, or yourself apply for a job abroad, you know the paperwork problem isn't really about translation quality. It's about tracking a pile of documents (employer letters, work certificates, reference letters) through multiple states: original → scanned → translated → certified → apostilled → submitted.

This is a document pipeline problem, and it's one developers are well equipped to solve, even with simple tooling. The legal and procedural side of certified translation for employment documents is covered well in this article on certified translation of employment experience letters. This post covers the technical side: how to build a lightweight system to manage the process instead of tracking it in your email inbox.

Why this is harder than it looks

A single international application can involve:

3-5 source documents (employer letters, certificates, performance reviews)
Each needing OCR-quality verification before translation
A certification step (lawyer or notary signature, in Portugal's case)
Possibly an apostille from a separate government body
Cross-referencing names and dates against a CV

Miss a stamp during scanning, or let one document's dates drift from your CV, and the whole application can bounce. This is exactly the kind of multi-step, stateful process that benefits from being modeled explicitly rather than tracked ad hoc.

Step 1: Validate scans before they go anywhere

The source article notes that "faint stamps or signatures cut off during scanning slow down certification." This is a solvable problem with basic image processing before you ever send a document to a translator.

A simple pre-check script using OpenCV and Tesseract can flag likely problem scans:

import cv2
import pytesseract

def check_scan_quality(image_path, min_text_confidence=60):
    img = cv2.imread(image_path)
    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

    # Flag low contrast (common cause of faint stamps)
    contrast = gray.std()
    if contrast < 40:
        print(f"WARNING: low contrast ({contrast:.1f}) — stamps may be unreadable")

    # Run OCR confidence check
    data = pytesseract.image_to_data(gray, output_type=pytesseract.Output.DICT)
    confidences = [int(c) for c in data['conf'] if c != '-1']
    avg_conf = sum(confidences) / len(confidences) if confidences else 0

    if avg_conf < min_text_confidence:
        print(f"WARNING: OCR confidence {avg_conf:.1f}% — rescan recommended")

    return {"contrast": contrast, "ocr_confidence": avg_conf}

This won't replace a human translator checking the document, but it catches the obvious failures (cut-off edges, washed-out stamps) before you waste a certification cycle on a bad scan.

Step 2: Build a document state machine

Each document in the application needs to move through a defined set of states. Modeling this explicitly, even in a spreadsheet or a small SQLite table, prevents the "did I already send this one" problem.

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

class DocState(Enum):
    COLLECTED = "collected"
    SCANNED = "scanned"
    SENT_FOR_TRANSLATION = "sent_for_translation"
    TRANSLATED = "translated"
    CERTIFIED = "certified"
    APOSTILLED = "apostilled"
    SUBMITTED = "submitted"

@dataclass
class Document:
    name: str
    doc_type: str  # employer_letter, reference_letter, certificate
    state: DocState = DocState.COLLECTED
    requires_apostille: bool = False
    dates_mentioned: list = field(default_factory=list)
    names_mentioned: list = field(default_factory=list)

    def can_submit(self):
        if self.requires_apostille:
            return self.state == DocState.APOSTILLED
        return self.state in (DocState.CERTIFIED, DocState.APOSTILLED)

The can_submit() check matters because it encodes exactly the rule the source article flags as a common mistake: documents go out without the apostille they actually needed, because someone assumed certification alone was enough.

Step 3: Cross-reference dates and names automatically

One of the stated reasons applications get rejected is inconsistent names and dates across documents. This is a text-matching problem you can partially automate.

import re
from datetime import datetime

def extract_dates(text):
    # crude pattern, adjust for your document formats
    pattern = r'\b(\d{1,2}[/-]\d{1,2}[/-]\d{2,4})\b'
    return re.findall(pattern, text)

def cross_check_documents(documents_text: dict, cv_text: str):
    cv_dates = set(extract_dates(cv_text))
    mismatches = {}

    for doc_name, text in documents_text.items():
        doc_dates = set(extract_dates(text))
        missing_in_cv = doc_dates - cv_dates
        if missing_in_cv:
            mismatches[doc_name] = missing_in_cv

    return mismatches

This isn't a substitute for careful proofreading, but running every document and your CV through a script like this before sending anything for certification catches the kind of typo that otherwise surfaces three weeks later when a qualifications body sends a rejection email.

Step 4: Track the certification and apostille chain

The source article explains that Portugal's certification model routes through a lawyer or notary, and the apostille is a separate step through the PGR. These are two different authorities with two different turnaround times, and conflating them in your tracking is how deadlines get missed.

If you're coordinating this for multiple documents or multiple family members' applications, a simple status table beats a scattered email thread:

Document	Certification status	Apostille needed	Apostille status	Submission deadline
Employer letter	Certified 03/14	Yes	Pending	04/01
Reference letter	Pending	No	N/A	04/01

Even a Google Sheet with conditional formatting on the deadline column solves 80% of the coordination problem. If you want something more durable, this maps cleanly onto a small Airtable base or a few tables in Postgres with a status enum matching the DocState above.

Where this pipeline actually ends

None of this replaces the legal step. A script can flag a blurry stamp, but it can't certify a translation, and it definitely can't decide whether your destination country needs an apostille or consular legalisation. That part is a legal and procedural question, covered in detail in the source article on certified translation for employment experience letters.

What this pipeline does is remove the operational noise: bad scans, missed apostille steps, and inconsistent dates, so that by the time a document reaches a certified translator or a notary, it's actually ready to be processed correctly the first time.

If you're building something similar for your own relocation or for a team handling multiple applicants, start with the state machine. Everything else (OCR checks, date matching, deadline tracking) can be added incrementally once you have a clear model of what state each document is actually in.

Building a Data Pipeline to Track PRO Questionnaire Translation Status Across Trial Sites

Diogo Heleno — Mon, 12 Oct 2026 15:31:05 +0000

Clinical trial teams running multicentre studies usually end up managing linguistic validation status in a spreadsheet. Someone owns a tab per language, tracks which version is in forward translation, which is stuck waiting on cognitive debriefing, and which has final sign-off from the copyright holder. This works until you have 15 countries and three PRO instruments running in parallel, at which point nobody actually knows what's blocking submission.

The source article on linguistic validation for PRO questionnaires covers the regulatory and methodological side well: why word-for-word translation fails, what ISPOR-based validation looks like, and what EMA/FDA reviewers expect in the dossier. This piece is about the engineering problem underneath that process: how do you track, version, and audit a multi-stage linguistic workflow without losing your mind in email threads and Word docs with tracked changes.

Why this is a state machine problem, not a document problem

Linguistic validation has a fixed, ordered sequence of states:

DRAFT -> FORWARD_TRANSLATION -> RECONCILIATION -> BACK_TRANSLATION
      -> COPYRIGHT_HOLDER_REVIEW -> COGNITIVE_DEBRIEFING
      -> HARMONISATION -> FINAL_SIGNOFF

Each state has:

An owner (translator, reviewer, patient panel coordinator, copyright holder)
An expected duration
Required artifacts before it can transition (translation report, discrepancy log, debriefing notes)
A rollback path (debriefing can send an item back to reconciliation)

This maps cleanly onto a state machine, and modeling it as one instead of a folder of documents gives you queryable status, audit trails for free, and the ability to catch bottlenecks before they delay submission.

A minimal schema

You don't need a full LIMS-style system to get value here. A relational schema with a handful of tables covers most of it:

CREATE TABLE pro_instrument (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  source_language TEXT NOT NULL,
  copyright_holder TEXT NOT NULL
);

CREATE TABLE instrument_item (
  id SERIAL PRIMARY KEY,
  instrument_id INT REFERENCES pro_instrument(id),
  item_code TEXT NOT NULL,
  source_text TEXT NOT NULL
);

CREATE TABLE validation_run (
  id SERIAL PRIMARY KEY,
  instrument_id INT REFERENCES pro_instrument(id),
  target_language TEXT NOT NULL,
  target_locale TEXT, -- pt-PT vs pt-BR, en-GB vs en-US
  status TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT now()
);

CREATE TABLE validation_event (
  id SERIAL PRIMARY KEY,
  run_id INT REFERENCES validation_run(id),
  stage TEXT NOT NULL,
  actor TEXT NOT NULL,
  artifact_url TEXT,
  notes TEXT,
  created_at TIMESTAMP DEFAULT now()
);

CREATE TABLE discrepancy (
  id SERIAL PRIMARY KEY,
  run_id INT REFERENCES validation_run(id),
  item_id INT REFERENCES instrument_item(id),
  stage_found TEXT NOT NULL,
  description TEXT,
  resolution TEXT,
  resolved_at TIMESTAMP
);

The target_locale field matters more than it looks. The source article flags that UK English and US English versions of the same instrument still need separate harmonisation passes. If your schema treats "English" as one language, you'll merge data that regulators expect to see tracked separately.

Enforcing valid transitions in code

A simple guard function keeps the workflow honest and prevents someone from fat-fingering a status update that skips cognitive debriefing:

VALID_TRANSITIONS = {
    "DRAFT": ["FORWARD_TRANSLATION"],
    "FORWARD_TRANSLATION": ["RECONCILIATION"],
    "RECONCILIATION": ["BACK_TRANSLATION"],
    "BACK_TRANSLATION": ["COPYRIGHT_HOLDER_REVIEW"],
    "COPYRIGHT_HOLDER_REVIEW": ["COGNITIVE_DEBRIEFING", "RECONCILIATION"],
    "COGNITIVE_DEBRIEFING": ["HARMONISATION", "RECONCILIATION"],
    "HARMONISATION": ["FINAL_SIGNOFF"],
    "FINAL_SIGNOFF": [],
}

def transition(run, new_status, actor, artifact_url=None, notes=None):
    if new_status not in VALID_TRANSITIONS[run.status]:
        raise ValueError(
            f"Cannot move from {run.status} to {new_status}"
        )
    log_event(run.id, new_status, actor, artifact_url, notes)
    run.status = new_status
    run.save()

Notice the rollback edges: copyright holder review and cognitive debriefing can both send a run back to reconciliation. That's the real-world behavior the source article describes, where a patient in cognitive debriefing misreads an item and it has to be reworded before harmonisation. If your tracking system can't represent that loop, people will just stop using it and go back to spreadsheets.

Flagging the stage people skip

The article calls out cognitive debriefing as the step most often cut when deadlines tighten. That's a monitoring problem as much as a process one. A simple query against the schema above tells you exactly which runs skipped it:

SELECT vr.id, vr.target_language
FROM validation_run vr
WHERE vr.status = 'FINAL_SIGNOFF'
AND NOT EXISTS (
  SELECT 1 FROM validation_event ve
  WHERE ve.run_id = vr.id AND ve.stage = 'COGNITIVE_DEBRIEFING'
);

Run that before any submission package goes out. It's cheap insurance against the exact failure mode the source article describes: outlier data from one site showing up in statistical analysis months after the fact, when nobody connected it back to a skipped debriefing round.

Generating the documentation package automatically

Regulators want specific artifacts: translation report, discrepancy log, debriefing report, harmonisation certificate, and copyright holder sign-off. If every event is logged with an artifact URL and timestamp, assembling the dossier is a query plus a templating step, not a manual scramble:

def build_submission_package(run_id):
    events = get_events(run_id)
    discrepancies = get_discrepancies(run_id)
    return render_template(
        "linguistic_validation_report.html",
        events=events,
        discrepancies=discrepancies,
        signoff=get_final_signoff(run_id),
    )

This also makes it trivial to cross-check terminology consistency between the PRO instrument and the clinical trial protocol translation, since both can be tracked as linked entities with their own event logs and diffed for inconsistent terms.

Where this fits with your translation vendor

None of this replaces the linguistic expertise required for forward translation, back translation, or running cognitive debriefing sessions with actual patients. That work needs qualified translators and a structured methodology, which is what firms doing ISO 17100 certified pharmaceutical translation work provide.

What the tooling buys you is visibility: knowing in real time which of your 15 country versions are stuck, which skipped a required stage, and whether your documentation will actually hold up when a reviewer asks for the discrepancy log at 2am before a submission deadline.

If you're coordinating validation across multiple instruments and multiple trial sites, it's worth spending a day building this kind of tracking layer before your second multicentre study, not during your fifth one.

Building a Multilingual Compliance Pipeline for CSDDD Supplier Documentation

Diogo Heleno — Mon, 12 Oct 2026 15:29:57 +0000

Compliance teams dealing with CSDDD requirements are discovering a problem that looks like a translation task but is actually a data and workflow problem. If your company has suppliers in a dozen countries, you don't need a one-off translation job. You need a pipeline: versioned source documents, a controlled glossary, a way to track who received what version in which language, and proof of acknowledgment that holds up under audit.

This is a problem developers are well positioned to solve, even if the actual translation still needs human linguists for anything legally binding. Here's how to think about the technical side of it.

Why this isn't a solved problem with off-the-shelf i18n tools

If you've built multilingual products, your instinct is to reach for the standard i18n stack: extract strings, push to a translation management system, pull back localized files, ship. That works fine for UI copy. It breaks down for compliance documents for a few reasons:

The content isn't strings in a codebase, it's long-form legal and normative text in Word or PDF
Terminology has to match international legal standards (ILO conventions, human rights language), not just read naturally
You need an audit trail: timestamps, versions, who translated what, who reviewed it, and proof of supplier acknowledgment
Machine translation introduces exactly the kind of terminology drift that fails an audit, as the source article on CSDDD supplier code of conduct translation points out

So the pipeline you build looks more like a document management + workflow automation system with translation as one stage, not a typical TMS setup.

A practical architecture for this pipeline

Here's a rough shape that works whether you're building this in-house or integrating with a translation vendor's API.

1. Source of truth for the document

Keep the approved code of conduct in version control, even if it's not code. A private git repo with the document in Markdown or structured XML (DocBook, DITA) gives you diffs, history, and the ability to track exactly what changed between CSDDD amendments.

# structure example
compliance-docs/
  code-of-conduct/
    v1.2-en.md
    v1.2-en.CHANGELOG.md
    glossary.yaml

2. A validated glossary as structured data

This is the part teams skip and then regret. Terms like "forced labour" or "living wage" need one approved translation per target language, locked by legal/compliance before anything goes to a translator.

# glossary.yaml
forced_labour:
  en: "forced labour"
  pt: "trabalho forçado"
  fr: "travail forcé"
  status: validated_by_legal
  source: ILO_C029
living_wage:
  en: "living wage"
  pt: "salário digno"
  fr: "salaire décent"
  status: validated_by_legal

Feed this glossary into whatever translation workflow you use, whether that's a vendor's CAT tool via API or an internal review tool. Translation memory systems (SDL Trados, memoQ, Phrase) all support glossary import, and most expose APIs to automate this instead of uploading files by hand each cycle.

3. Workflow state machine, not a spreadsheet

Track each document through states: draft -> legal_approved -> sent_for_translation -> translated -> reviewed -> sent_to_supplier -> acknowledged. A lot of teams track this in a spreadsheet and it falls apart past 20 suppliers in 7 languages. A simple state machine, even just a Postgres table with triggers, scales better and gives you a queryable audit log.

CREATE TABLE supplier_document_status (
  id SERIAL PRIMARY KEY,
  supplier_id INT REFERENCES suppliers(id),
  document_version TEXT,
  language TEXT,
  state TEXT, -- draft, legal_approved, translated, reviewed, sent, acknowledged
  acknowledged_at TIMESTAMP,
  acknowledgment_method TEXT, -- e-signature, signed PDF, portal click
  created_at TIMESTAMP DEFAULT now()
);

This table alone answers the auditor's question: "prove supplier X in Bangladesh received and acknowledged version 1.2 in Bengali." Without it, you're digging through email threads.

4. Acknowledgment as a tracked event, not an assumption

Sending the PDF is not due diligence. You need a mechanism that records acceptance. Options depending on your stack:

An e-signature API (DocuSign, HelloSign) tied to supplier records
A supplier portal where login + click-to-accept is logged with IP/timestamp
A signed PDF returned and hashed/stored for integrity checks

Whichever you pick, store the acknowledgment event with a reference to the exact document version and language, not just "code of conduct v1."

Where automation should stop

It's tempting to automate the translation step itself with an LLM or MT engine and call it done. Don't, at least not for the final legal text. The source article makes a solid case for why: legal and normative language needs human review against established terminology, and a second linguist review catches exactly the kind of material divergence that creates liability.

Where automation genuinely helps:

Pre-processing: extracting text, diffing versions, flagging which sections changed since the last approved version so translators only re-translate what's new
Glossary consistency checks: scripting a QA pass that flags terms translated inconsistently across files before human review
Routing: automatically determining which documents need the highest-rigor review tier versus which can go through a faster process, based on whether the document is attached to a binding contract

A quick example of a consistency check script:

import yaml, re

glossary = yaml.safe_load(open('glossary.yaml'))

def check_consistency(translated_text, lang):
    issues = []
    for term, data in glossary.items():
        expected = data.get(lang)
        if expected and expected.lower() not in translated_text.lower():
            issues.append(f"Missing validated term '{expected}' for '{term}'")
    return issues

This won't replace a linguist, but it catches obvious drift before the document goes to expensive human review, saving a review cycle.

The real takeaway

CSDDD compliance for supplier documentation is less a translation challenge and more a document lifecycle challenge. If you're the engineer asked to "help compliance with the translation thing," push for version control, a structured glossary, and an explicit acknowledgment-tracking system before anyone talks about which CAT tool or vendor to use. The tooling matters less than having a system that can answer an auditor's questions in minutes instead of days.

For the legal and process side, like which documents need certified translation versus internal-only translation, and how review tiers map to legal risk, the source article at m21global.com covers that ground well.

Building an i18n Pipeline That Doesn't Break on Plurals and RTL Languages

Diogo Heleno — Mon, 12 Oct 2026 15:29:48 +0000

Most i18n bugs aren't discovered by developers. They're discovered by a Polish user who sees "5 wiadomości" rendered as "5 wiadomość", or by an Arabic user staring at a button that got clipped because the translated string is 40% longer than the English original.

The source article from M21Global, preparing software files for localisation, lays out the linguistic reasons these bugs happen: plural categories, gendered strings, word order. This article is the implementation side — how to actually build a pipeline and codebase that doesn't generate this class of bug in the first place.

Stop concatenating strings, even "just this once"

Every team knows concatenation is bad practice. Every team still does it under deadline pressure:

// Don't do this
const message = "User " + userName + " has " + count + " messages";

The fix isn't just moving to template literals. It's moving the whole sentence into a resource key with named placeholders, so the translator controls word order:

{
  "messageCount": "User {userName} has {messageCount} messages"
}

With i18next:

import { useTranslation } from 'react-i18next';

const { t } = useTranslation();
t('messageCount', { userName: 'Alice', messageCount: 3 });

The translator working on the German or Arabic file edits the whole string, including reordering the placeholders if the grammar demands it. Your code never changes.

Implementing CLDR plural rules instead of if/else trees

If your codebase has logic like this, it will break for any language beyond English:

// Breaks for Polish, Russian, Arabic...
function pluralize(count) {
  return count === 1 ? 'item' : 'items';
}

CLDR defines up to six plural categories (zero, one, two, few, many, other) depending on the language. i18next, ICU MessageFormat and gettext all implement this out of the box. With i18next, the resource file looks like:

{
  "item": "{{count}} item",
  "item_other": "{{count}} items"
}

For a language with more categories, like Polish:

{
  "item_one": "{{count}} przedmiot",
  "item_few": "{{count}} przedmioty",
  "item_many": "{{count}} przedmiotów",
  "item_other": "{{count}} przedmiotu"
}

The library picks the right key based on the CLDR rules for that locale. You never write the conditional yourself. If you're on ICU MessageFormat instead:

{count, plural,
  one {# item}
  other {# items}
}

Test checklist for any pluralized string: run it with 0, 1, 2, 5, 11, 21 and 100. Those values expose edge cases in Slavic and Arabic plural rules that 1 and 2 alone won't catch.

Automated tests that catch localisation bugs before a human does

Most teams test translations by eyeballing the UI in one or two languages. That doesn't scale and doesn't catch plural bugs. A better approach is a lint step in CI that checks:

Every key in the base locale (en.json) exists in every target locale file
No locale file has orphaned keys that don't exist in the base file
Every pluralizable key has an other fallback
No placeholder ({userName}) is missing from a translated string

A simple Node script for the placeholder check:

const fs = require('fs');

function extractPlaceholders(str) {
  return [...str.matchAll(/{(\w+)}/g)].map(m => m[1]).sort();
}

function checkLocale(base, target) {
  const errors = [];
  for (const key in base) {
    if (!target[key]) continue;
    const basePH = extractPlaceholders(base[key]);
    const targetPH = extractPlaceholders(target[key]);
    if (JSON.stringify(basePH) !== JSON.stringify(targetPH)) {
      errors.push(`Mismatch in "${key}": expected [${basePH}], got [${targetPH}]`);
    }
  }
  return errors;
}

const en = JSON.parse(fs.readFileSync('en.json'));
const de = JSON.parse(fs.readFileSync('de.json'));
console.log(checkLocale(en, de));

Run this on every PR that touches a locale file. It catches a translator accidentally dropping {orderDate} before it reaches production, which is far cheaper than catching it after a customer reports a broken order confirmation email.

Picking a format that survives the round trip

The format you export from matters more than most teams assume:

Format	Good for	Watch out for
JSON	React, Vue, Node backends	No native comment support, easy to lose context
.resx	.NET apps	Comments supported per string, verbose XML
.po/.pot	gettext, WordPress	Mature tooling, plural forms built in
XLIFF	Vendor handoff	Preserves placeholders and comments, harder to hand-edit
ARB	Flutter	Native ICU plural support

If you're shipping JSON straight to a translation vendor without an intermediate format, you're relying entirely on key naming to convey context. That's fragile. A cheap workaround if you're staying in JSON is a parallel comments file or a _comment key convention:

{
  "checkoutButton": "Complete order",
  "checkoutButton_comment": "Primary CTA, checkout screen, max 20 characters"
}

It's not as clean as .resx metadata or XLIFF's <note> elements, but it stops the translator from guessing.

Wiring this into CI/CD

For teams shipping continuously, the manual export-translate-import cycle doesn't scale. A reasonable pipeline:

Developer adds a new key to en.json as part of a feature PR
CI lint step flags missing placeholders/comments before merge
On merge to main, a script diffs the base locale against the last exported version and pushes only new/changed keys to the translation platform (Crowdin, Lokalise, Phrase, or an XLIFF export for a vendor)
Translated strings come back via webhook or scheduled pull, open as an automated PR
A second lint pass validates placeholder parity and plural completeness before that PR can merge

This keeps translation off the critical path for shipping a feature in your base language, while making sure localisation debt doesn't silently accumulate.

Where the two articles meet

The M21Global piece makes the case for why resource files need to be CLDR-aware, placeholder-named and context-commented before they ever leave engineering. Everything above is how you enforce that mechanically, with tests and CI gates instead of a style guide nobody reads. If you're setting this up for the first time, start with the lint script. It's the cheapest way to turn a localisation convention into something that actually holds.

Building a Document Pipeline for Professional Credential Recognition (Apostille, Translation, Submission)

Diogo Heleno — Mon, 12 Oct 2026 07:28:06 +0000

Credential recognition workflows show up more often than you'd expect in internal tooling: HR platforms for relocating employees, immigration case management systems, university partnership portals, government digital services. If you've ever been asked to build or maintain one of these, you know the hard part isn't the UI. It's modeling a process that varies by country, by institution, and by document type, with almost no API coverage.

This post walks through how to think about that problem technically, using professional recognition for doctors and engineers in Portugal as a concrete case study. The source article on certified translation for medical and engineering boards covers the regulatory side well. This is the implementation side: how you'd model the document states, catch errors before submission, and avoid building a system that silently produces rejected applications.

Why this is a state machine problem, not a form problem

Most teams start by building a form: upload diploma, upload transcript, submit. That works until you realize each document independently moves through a sequence of states, and the sequence order itself is a variable.

For a Portuguese professional board application, a single document can pass through:

original
apostilled or legalised
translated
certified (lawyer/notary attestation)
submitted
accepted / returned_for_correction

The catch, directly from the source material: whether apostille happens before or after translation depends on the country of origin and the specific board. That's not an edge case, it's the normal case. If you hardcode a linear pipeline (translate → apostille → submit), you will build something that's wrong for a meaningful chunk of your users.

Model it instead as a directed graph per country/board combination, not a single pipeline:

# Simplified representation of per-country document flow
DOCUMENT_FLOWS = {
    ("BR", "Ordem dos Medicos"): ["original", "apostille", "translate", "certify", "submit"],
    ("AO", "Ordem dos Engenheiros"): ["original", "legalise", "translate", "certify", "submit"],
    ("FR", "Ordem dos Medicos"): ["original", "translate", "apostille", "certify", "submit"],
}

def get_flow(country_code: str, board: str) -> list[str]:
    flow = DOCUMENT_FLOWS.get((country_code, board))
    if not flow:
        raise LookupError(f"No confirmed flow for {country_code}/{board}. Flag for manual review.")
    return flow

The LookupError branch matters as much as the happy path. The source article is explicit that step order should be confirmed directly with the board's secretariat. Your system should treat unconfirmed country/board combinations as a hard stop, not a default guess.

Catching terminology inconsistency before a human does

The article flags something that's easy to dismiss as a soft skill problem but is actually very solvable with tooling: inconsistent terminology across documents in the same file. "Strength of materials" vs "mechanics of materials" on an engineering transcript isn't a style nitpick, it can change an equivalence decision.

If you're running translation through any kind of managed workflow (even a human-in-the-loop one, since this is certified legal translation, not raw MT), you can still build a terminology consistency check as a pre-submission gate.

A basic approach:

Maintain a per-case glossary (subject names, degree titles, institution names) as the source of truth.
Extract candidate terms from each translated document (OCR + NER if working from PDFs, or direct text diffing if you control the translation memory).
Flag any term that deviates from the glossary above a similarity threshold, rather than matching exactly.

from difflib import SequenceMatcher

def check_term_consistency(glossary: dict[str, str], extracted_terms: list[str], threshold=0.85):
    flags = []
    for term in extracted_terms:
        best_match = max(glossary.values(), key=lambda g: SequenceMatcher(None, term, g).ratio())
        score = SequenceMatcher(None, term, best_match).ratio()
        if 0 < score < threshold:
            flags.append((term, best_match, round(score, 2)))
    return flags

This won't replace a linguist's review (and for high-stakes documents it shouldn't), but it's a cheap gate that catches the exact failure mode the source article describes, before a human reviewer or a board clerk does.

Name and date normalization across documents

Another flagged failure mode: inconsistent transliteration of a candidate's name across documents triggers clarification requests. This is a solved problem in data engineering, just apply it here.

Normalize all personal identifiers (name, DOB, document numbers) into a canonical record per applicant at intake.
Run every subsequently uploaded document's extracted metadata against that canonical record.
Diff mismatches and surface them before submission, not after a board returns the file.

def validate_identity_fields(canonical: dict, extracted: dict) -> list[str]:
    mismatches = []
    for field in ("full_name", "date_of_birth", "passport_number"):
        if canonical.get(field) != extracted.get(field):
            mismatches.append(field)
    return mismatches

This is unglamorous, but it directly prevents one of the five recurring delay causes the source article lists.

A minimal checklist structure for the pipeline

If you're building this as an internal tool rather than a full product, you can get most of the value from a structured checklist model instead of a full workflow engine:

Document requirements table per board (medical vs engineering, since the lists differ)
Per-document status tracking (original / legalised / translated / certified)
A hard validation step before submission: every required document present, every annex and stamp included, consistent terminology, consistent identity fields
An explicit "confirm sequence with board secretariat" flag for any country/board pair not yet verified

This maps cleanly onto a relational schema if you want to persist it: applications, documents, document_states, glossary_terms, each scoped by (country, board).

Where this generalizes

None of this is specific to Portugal or to medicine and engineering. Any cross-border credential recognition system, legal document localization, or immigration case tool has the same shape: country-specific sequencing, terminology consistency requirements, and identity field validation. If you're building in this space, model the variability explicitly instead of assuming a single linear pipeline, and you'll avoid most of the failure modes that cause real-world applications to bounce back for correction.

For the regulatory detail on what each board actually requires and how certification works under Portuguese rules, the original article is worth reading in full: certified translation for medical and engineering boards.

Building a Document Pipeline for Certified Translations: A Technical Breakdown

Diogo Heleno — Thu, 08 Oct 2026 06:03:33 +0000

Legal document workflows are a weirdly underserved problem in software. Most of us have built pipelines for CI/CD, data ETL, or content localization in apps, but document certification chains, apostilles, consular legalisation, sworn translations, are a different beast. They're sequential, stateful, jurisdiction-dependent, and a single out-of-order step invalidates everything downstream.

I got interested in this after reading a breakdown of certified translation requirements for birth certificates in dual nationality applications. The source article is aimed at applicants, but reading it through an engineering lens, it's basically describing a fragile state machine that a lot of people manage manually with folders, spreadsheets, and panic emails to consulates.

This post looks at how you'd actually model that process if you were building tooling for it, whether for a legal-tech product, an internal ops tool at a translation agency, or just to understand why these workflows break so often.

The process is a strict state machine, not a checklist

The most common failure mode described in the source material is translating a document before it's apostilled or legalised. That's not a paperwork nuance, it's a sequencing bug. The translation has to reference the final, stamped version of the document, including the apostille text itself. Translate first and you've produced an artifact that doesn't correspond to the thing it's supposed to be a translation of.

If you model this as a state machine, it looks roughly like:

DRAFT_DOCUMENT
  -> ISSUED (by civil registry)
  -> LEGALISED (apostille OR consular legalisation, mutually exclusive paths)
  -> TRANSLATED (certified, referencing the legalised version)
  -> SUBMITTED (to receiving authority)

The branch at LEGALISED matters. Whether a document takes the apostille path or the consular legalisation path depends entirely on whether the issuing country is a party to the Hague Apostille Convention. That's a lookup against a dataset that changes over time (countries join conventions, bilateral agreements shift).

If you're building anything in this space, that lookup table shouldn't be hardcoded. Treat it like a feature flag service or a pricing table: versioned, dated, with an audit trail, because "is Angola in the Apostille Convention" needs an answer you can prove was correct at the time of submission, not just currently.

Modeling certification requirements per jurisdiction

The other hard part is that "certified translation" means different things in different countries:

Portugal: sworn translation (tradução juramentada), signed and stamped by a recognised translator
Italy: sworn before a court
Brazil: only a public sworn translator registered with the Junta Comercial

This is a classic rules-engine problem. If you were encoding this as data instead of prose, you'd want something like:

{
  "country": "PT",
  "document_type": "birth_certificate",
  "certification_type": "sworn_translation",
  "authorized_certifiers": ["recognised_sworn_translator"],
  "legalisation_required": "apostille_or_consular",
  "accepting_authority": ["CRC", "PT_consulate"]
}

The value of structuring it this way isn't just tidiness. It lets you validate a case before money is spent on translation. A huge share of the delays mentioned in the source article (wrong certifier, missing declaration, wrong order) are preventable with a validation pass against rules like these before a human ever touches the document.

Translation completeness is a parsing problem

One detail that's easy to gloss over: partial translation. Authorities reject translations that skip marginal annotations, registration references, or post-registration notes. From a tooling perspective, this is a document-completeness check, conceptually similar to validating that a translated JSON file has the same key set as the source.

If you're dealing with OCR'd or digitized civil documents, you can approximate this with a diff-style check:

def check_translation_completeness(source_fields, translated_fields):
    missing = set(source_fields) - set(translated_fields)
    if missing:
        raise ValueError(f"Untranslated fields detected: {missing}")
    return True

In practice the "fields" aren't neatly structured, civil registry documents have handwritten marginal notes, stamps, and annotations added over years, so this isn't a clean automation target. But even a manual checklist generated from a structured template (what fields should exist on a Portuguese birth certificate issued post-1911 reform, for instance) catches a meaningful share of the "partial translation" rejections.

Proper noun consistency across a document set

The source article flags inconsistent transliteration of names and place names across documents as a trust signal that raises red flags with authorities. This is a solvable problem with a translation memory (TM) system, the kind CAT tools (Trados, memoQ, Smartcat) already implement.

If you're coordinating translations across multiple related documents (birth certificate, parent's birth certificate, marriage certificate) for the same case, you want a shared glossary enforced across all of them:

glossary:
  - source: "João Manuel Silva"
    target_en: "João Manuel Silva"  # names typically aren't translated
  - source: "Freguesia de Arcos"
    target_en: "Arcos Parish"
    target_consistency: strict

If you're building or evaluating tooling for a translation agency handling nationality cases, check whether it enforces glossary consistency across documents in the same case, not just within a single file. Most CAT tools handle intra-document consistency well; cross-document, case-level consistency is where custom tooling adds real value.

Where this intersects with i18n work more broadly

If you work in i18n/l10n tooling for products, a lot of this will feel familiar: source-of-truth versioning, pipeline ordering, terminology consistency, validation before expensive human steps. The regulatory stakes are higher here (a rejected nationality application can cost months, not a bad UI string) but the architecture problem is the same shape.

If you're building anything adjacent to this space, legal-tech, immigration tooling, document automation, it's worth reading the original article not as a how-to for applicants, but as a spec for the failure modes your system needs to prevent.

The full breakdown of certification types, document lists, and legalisation order is here: Certified Translation of Birth Certificates for Dual Nationality.

Building a Terminology Pipeline for Multi-Jurisdiction Tax Compliance (Pillar Two and Beyond)

Diogo Heleno — Wed, 07 Oct 2026 11:53:08 +0000

Tax and compliance teams aren't the only ones who feel the pain of Pillar Two reporting. If you work on internal tooling for finance, legal, or compliance departments at a multinational, you've probably been asked to build or maintain some version of a "generate the GloBE Information Return in six languages without anyone catching a terminology mismatch" system.

That's a data consistency problem as much as a translation problem, and it's one we can actually solve with tooling instead of throwing more reviewers at it.

A good breakdown of the business side of this (what documents are needed, what certification applies, why a wrong term in the GIR can trigger a reassessment) is covered in this article on Pillar Two translation. This post picks up where that leaves off: how do you actually build a pipeline that keeps terminology consistent across jurisdictions, document types, and translation vendors?

The real problem: terminology drift across a document graph

A multinational filing in six jurisdictions isn't translating one document six times. It's maintaining a graph of related documents:

GloBE Information Return (standardized OECD form, fixed terminology)
Technical calculation notes (free text, technical tax language)
Transfer pricing policies referenced in annexes
Correspondence with local authorities
Internal board/audit reports

Each document type has different reviewers, different update frequency, and different translation requirements (certified vs. not). If each subsidiary's local team handles its own translation independently, you get exactly the failure mode described in the source article: the German entity calls it one thing, the Spanish entity calls it another, and now an auditor is asking why.

This is a single-source-of-truth problem. Treat it like one.

Step 1: Build a canonical terminology store, not a glossary doc

A shared spreadsheet glossary works until it doesn't scale past two languages. Instead, model your terminology as structured data:

{
  "term_id": "QDMTT",
  "canonical_en": "Qualified Domestic Minimum Top-up Tax",
  "definition": "OECD Pillar Two mechanism allowing a jurisdiction to collect top-up tax domestically before it is collected elsewhere.",
  "translations": {
    "de": { "term": "Qualifizierte inländische Ergänzungssteuer", "locked": true, "source": "BMF guidance 2024" },
    "es": { "term": "Impuesto complementario nacional cualificado", "locked": true, "source": "AEAT terminology" },
    "fr": { "term": "Impôt national complémentaire qualifié", "locked": true, "source": "DGFiP guidance" }
  },
  "do_not_translate_literally": true,
  "notes": "Acronym and exact term vary by jurisdiction; check local tax authority's adopted wording before use."
}

Storing this as structured data means you can:

Validate it programmatically (no missing languages, no duplicate IDs)
Feed it directly into CAT tools or MT engines as a termbase
Diff it over time to catch when someone silently changes a locked term

Step 2: Feed the termbase into your translation tooling

Most professional CAT tools (memoQ, Trados, Phrase) accept termbases in TBX format. You can generate TBX from your JSON/YAML source with a small script:

import json
from lxml import etree

def build_tbx(terms, output_path):
    root = etree.Element("martif", type="TBX")
    text = etree.SubElement(root, "text")
    body = etree.SubElement(text, "body")

    for term in terms:
        entry = etree.SubElement(body, "termEntry", id=term["term_id"])
        for lang, data in term["translations"].items():
            langset = etree.SubElement(entry, "langSet")
            langset.set("{http://www.w3.org/XML/1998/namespace}lang", lang)
            tig = etree.SubElement(langset, "tig")
            term_el = etree.SubElement(tig, "term")
            term_el.text = data["term"]

    tree = etree.ElementTree(root)
    tree.write(output_path, pretty_print=True, xml_declaration=True, encoding="UTF-8")

with open("termbase.json") as f:
    terms = json.load(f)

build_tbx(terms, "pillar_two_termbase.tbx")

If your organization uses machine translation as a first pass before human review (common for triaging large volumes of historical transfer pricing files), most MT APIs support custom glossaries directly:

import deepl

translator = deepl.Translator(auth_key)

glossary = translator.create_glossary(
    "pillar_two_de",
    source_lang="EN",
    target_lang="DE",
    entries={"Qualified Domestic Minimum Top-up Tax": "Qualifizierte inländische Ergänzungssteuer"}
)

result = translator.translate_text(
    document_text,
    source_lang="EN",
    target_lang="DE",
    glossary=glossary
)

This won't replace certified human translation for documents going to tax authorities, but it's genuinely useful for the triage step: deciding which of 400 pages of annexes actually need full professional translation versus which can stay as reference material.

Step 3: Version and lock terms the same way you version an API contract

Tax terminology isn't static. OECD guidance gets updated, local authorities adopt new preferred terms, and your own group's financial reporting language evolves. Treat your termbase like a versioned artifact:

Tag releases (v2024.1, v2025.1) tied to filing periods
Require a PR-style review before a locked term changes
Keep a changelog explaining why a term changed (regulatory update vs. internal style preference)

git log --oneline -- termbase/pillar_two.json
a1b2c3d v2025.1: update QDMTT acronym for PT jurisdiction per AT guidance
f4e5d6a v2024.2: lock ETR translation to match consolidated accounts wording

This gives you an audit trail, which matters a lot if a tax authority later questions why a term changed between filing years.

Step 4: Automate consistency checks, don't rely on reviewers to catch drift

A simple script comparing translated documents against the locked termbase catches most drift before it reaches a human reviewer:

import re

def check_term_consistency(document_text, termbase, lang):
    issues = []
    for term in termbase:
        canonical = term["translations"].get(lang, {}).get("term")
        if not canonical:
            continue
        variants = term.get("known_incorrect_variants", {}).get(lang, [])
        for variant in variants:
            if re.search(variant, document_text, re.IGNORECASE):
                issues.append((term["term_id"], variant, canonical))
    return issues

Run this as a CI step on any translated document before it goes to certification. It's not a replacement for a qualified reviewer, but it stops the cheap mistakes (a stale term left over from a previous filing year, a translator unaware of the locked glossary) from reaching the expensive part of the pipeline.

Where this fits with certified translation workflows

None of this replaces the need for sworn or certified translation where a jurisdiction requires it. What it does is make the human translation step faster and more consistent, because the translator receives a document with terminology already locked, rather than having to make judgment calls on ambiguous terms like QDMTT or UTPR for the fifth time across five subsidiaries.

If your organization is working through which documents need certified translation versus internal review only, and how to structure the vendor relationship across jurisdictions, the source article on Pillar Two documentation covers that side of the problem well. The tooling above is what makes that process scale past two or three jurisdictions without someone manually cross-checking six spreadsheets before a filing deadline.