DEV Community

Cover image for Building a Document Requirements Checker for International Civil Registration Workflows
Diogo Heleno
Diogo Heleno

Posted on Originally published at m21global.com

Building a Document Requirements Checker for International Civil Registration Workflows

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
Enter fullscreen mode Exit fullscreen mode

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 }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)