DEV Community

Cover image for Building a Document Pipeline for International School Enrolment Paperwork (Apostille Certified Translation Submission)
Diogo Heleno
Diogo Heleno

Posted on Originally published at m21global.com

Building a Document Pipeline for International School Enrolment Paperwork (Apostille Certified Translation Submission)

Every September, the same support ticket shows up in relocation forums and Slack groups for expat parents: "What order do I do apostille, translation, and legalisation in, and why did the school reject my document?"

This isn't really a translation problem. It's a workflow problem, and workflow problems are things developers are good at modeling. The original article on the M21Global blog covers the legal side well: what counts as certified translation in Portugal, which documents schools ask for, and when an apostille is required before anything else happens.

What I want to cover here is the complementary piece: how to think about this as a state machine with external dependencies, so you (or your org's HR/relocation team, or a tool you build) stop losing weeks to sequencing mistakes.

Model it as a pipeline, not a checklist

The mistake most families make is treating this as a flat checklist: "get transcript, get it translated, get it certified, done." In reality it's a directed graph with hard ordering constraints. Each document has its own path depending on:

  • Country of origin (Hague Apostille Convention member or not)
  • Document type (transcript vs diploma vs birth certificate)
  • Destination requirement (school enrolment vs residency process vs both)

A minimal state machine for a single document looks like this:

ORIGINAL_ISSUED
  -> NEEDS_LEGALIZATION? (check HCCH table for origin country)
      yes -> APOSTILLED or CONSULAR_LEGALIZED
      no  -> skip
  -> TRANSLATION_REQUESTED
  -> TRANSLATION_CERTIFIED (lawyer or notary sign-off, Portugal-specific)
  -> SUBMITTED_TO_SCHOOL
  -> ACCEPTED or REJECTED (missing doc, wrong grading scale mapping, etc.)
Enter fullscreen mode Exit fullscreen mode

The critical edge here is that APOSTILLED has to happen before TRANSLATION_REQUESTED. Reverse that order and you redo the whole branch. This is exactly the mistake the source article flags as the most common delay cause, and it's the kind of bug that's obvious once you draw it as a graph but invisible when it's just a to-do list in someone's email thread.

If you're coordinating this for more than one kid, or for an HR team handling multiple relocating employees, this is worth modeling explicitly, even in something as simple as a spreadsheet with status columns per document, or a small Airtable/Notion base with linked records per child and per document type.

A quick lookup script for apostille requirements

The HCCH (Hague Conference on Private International Law) publishes the status table of which countries are party to the Apostille Convention. If you're building any kind of relocation tool, or just want to avoid manually checking, you can script this check instead of guessing:

import requests

# HCCH publishes status tables per convention; convention #12 is the Apostille Convention
# This is illustrative - scrape or use a maintained dataset, HCCH doesn't offer a clean public API
HCCH_APOSTILLE_STATUS_URL = "https://www.hcch.net/en/instruments/conventions/status-table/?cid=41"

def needs_apostille_check(country_name: str) -> str:
    """
    Returns a reminder string. There is no official JSON API for HCCH status,
    so treat this as a manual verification step baked into your workflow,
    not something to fully automate without a maintained fallback.
    """
    return (
        f"Check {HCCH_APOSTILLE_STATUS_URL} for {country_name}. "
        f"If not a party to the convention, route is: "
        f"origin country ministry of foreign affairs -> Portuguese consulate legalisation."
    )

print(needs_apostille_check("Brazil"))
Enter fullscreen mode Exit fullscreen mode

This won't save you from checking the table yourself, HCCH doesn't expose a clean machine-readable API, but wrapping the check in a function forces whoever runs the process to actually look it up per document rather than assume based on a previous case. Assumptions are where the "redo the translation" mistake comes from.

Tracking document status without over-engineering it

You don't need a custom app for this. A simple structure, even in a markdown file or a shared sheet, gets you 90% of the value:

## Child: Maria | Target school: Agrupamento X | Deadline: Sept 15

| Document             | Origin   | Apostille needed? | Apostille status | Translation status | Certified? | Submitted? |
|----------------------|----------|--------------------|-------------------|----------------------|------------|------------|
| Grade transcript      | Spain    | No (EU doc)        | N/A                | In progress          | No         | No         |
| Completion certificate| Brazil   | Yes                 | Done               | Not started           | No         | No         |
| Birth certificate     | Brazil   | Yes                 | Pending            | Not started           | No         | No         |
Enter fullscreen mode Exit fullscreen mode

The column that matters most, and the one people skip, is "Apostille needed?" being answered explicitly per document, not assumed per country. Some documents from the same country have different legalisation paths depending on which authority issued them.

Naming and grading scale mapping is a data problem too

The source article mentions that subjects like "social studies" or "civics" don't map 1:1 to the Portuguese curriculum, and that grading scales (0-100, A-F, 1-10) need careful handling. If you're dealing with more than one document or more than one kid, it's worth keeping an explicit mapping table rather than relying on the translator to make consistent judgment calls across separate documents:

{
  "grading_scale_mapping": {
    "source_scale": "A-F",
    "target_scale": "0-20",
    "mapping": {
      "A": "18-20",
      "B": "15-17",
      "C": "12-14",
      "D": "10-11",
      "F": "0-9"
    },
    "notes": "Used only for informal pre-assessment, official equivalence is decided by school/DGEstE, not by this mapping."
  }
}
Enter fullscreen mode Exit fullscreen mode

This isn't a replacement for the official equivalence decision the school or Direção-Geral da Educação makes. It's a sanity check you can run before submission, so you're not surprised by how the translated document reads next to the original.

Practical takeaways

  • Treat apostille/legalisation and certified translation as sequential dependencies, not parallel tasks
  • Check the HCCH status table per document, not per country assumption
  • Keep an explicit status tracker, even a plain markdown table beats email threads
  • Ask the school in writing, up front, for the full list of documents assessed for year placement, not just the diploma
  • Don't assume a certified translation in one country (sworn translator model, e.g. Spain/Brazil) satisfies Portugal's lawyer/notary certification model, they're structurally different systems

If you're the one actually commissioning the certified translations, the legal detail (who's authorised to certify in Portugal, what ISO standards apply to the translation vendor) is covered well in the original piece here: https://www.m21global.com/en/blog/certified-translation-school-records-enrolment/. The workflow discipline is on you.

Top comments (0)