Fiz o Ghost funcionar com vários idiomas — e quis compartilhar

Oi! Eu fiz este blog usando Ghost, que é uma ferramenta/plataforma de blog/newsletter bem legal, mas ela não suporta vários idiomas muito bem, bem, não do jeito que eu gostaria.

Muita gente se enrola com um blog Ghost em vários idiomas, porque o Ghost simplesmente não dá conta disso direito. Ele consegue traduzir um tema, mas não tem ferramenta de verdade para artigos ou newsletters em vários idiomas. Eu realllllmente queria usar Ghost (por causa das newsletters e dos sistemas de membership), então tentei deixar isso i18n (amigável a vários idiomas). Este post é como eu fiz. Não vou escrever cada linha de código de produção — isso seria chato demais. Vou explicar o essencial, mostrar as peças que você realmente precisa inventar, e deixar um repo mínimo que você pode subir com docker compose up.

Se estiver com pressa, joga isto no LLM da sua preferência e pede para copiar o setup, provavelmente vai sair ok (mas eu não assumo responsabilidade!). Seja lá o que você decidir, se isso te ajudar, deixa uns kudos, um pouco de exposição e talvez me pague um café por ter te poupado dor de cabeça!

PS: Isto é para quem self-host Ghost. Se você está no Ghost(Pro), pode continuar lendo, mas vai ter que hospedar as peças extras você mesmo. Se não quiser isso, pode parar aqui.

PS de novo: vou falar de como os templates se comportam. Não vou te ensinar a criar um tema do zero. Para isso, leia Default template explained by the Ghost team e Write your own Ghost theme by Mat Duggan.

O Ghost fala um idioma por vez. Este site fala quatro — inglês (EUA), japonês, português brasileiro e espanhol latino-americano — sem fingir que o Ghost ganhou um módulo de tradução. O truque não é um “plugin de i18n”. São três sistemas pequenos que não se atrapalham: as palavras em volta do artigo (nav, botões, estados vazios), os artigos em si (um post Ghost por idioma, ligados por tags) e as listas de e-mail (uma newsletter por locale).

Se você lembrar de uma imagem só, lembre desta: templates com um helper compilado, posts com tags de idioma, uma newsletter para cada idioma. Eles compartilham uma lista de locales.

Índice

1. Por que o Ghost sozinho não basta
2. A lista de locales que todo o resto copia
3. As três camadas
4. Camada 1 — traduzir o template
5. Camada 2 — traduzir o artigo
6. Um servidorzinho Python para o mapa
7. Camada 3 — ligar o formulário da newsletter
8. Um passo a passo: publicar este texto em quatro idiomas
9. Checklist

Por que o Ghost sozinho não basta

O Ghost consegue traduzir o template — mais ou menos. O helper nativo {{t}} segue o idioma do site em Admin Settings. Mude o site para japonês e cada URL tenta falar japonês. Eu não queria isso. Queria cada idioma no próprio caminho: /en-us, /pt-br, /ja-jp, e por aí. Assim o idioma fica óbvio na URL (ótimo para SEO e para compartilhar) e redirects e detecção ficam chatamente simples, no bom sentido.

O Ghost também não tem um campo “este post é tradução daquele”. Um post é um post. Se você quer uma versão em japonês, cria um segundo post. Se quer que os dois se encontrem no seletor de idioma, você inventa o link.

Então o stack responde três perguntas separadas:

• Como o template sabe que está em /pt-br/?
• Como um artigo cai no índice certo, e como posts irmãos se encontram?
• Como o formulário de inscrição coloca alguém na lista em português em vez da inglesa?

A lista de locales que todo o resto copia

Comece aqui, antes mesmo de mexer no template. Se os idiomas morarem em cinco lugares diferentes, você vai passar o resto da vida caçando typo. Eu quis uma lista da qual o tema, as rotas de artigo e o mapa de tradução todos copiam. Adicione um idioma nessa lista e o resto deve conseguir seguir. Hard-code "japanese" num Handlebars aleatório e você esquece que existe.

Escolha os idiomas, depois um padrão

Anote para quem você realmente vai escrever. Não “todos os idiomas um dia” — os que você consegue manter. Para mim foram inglês (EUA), japonês, português brasileiro e espanhol latino-americano. Depois escolha um padrão. Esse locale é o lar de posts que saíram sem tag de idioma, e é para onde / manda as pessoas se o navegador não ajudar. O meu é inglês.

Você não precisa de quatro. Dois já é um site multilíngue de verdade. Você pode ter quantos idiomas quiser. Na verdade este setup não funciona só para idiomas, você poderia fazer a mesma coisa para regiões se realmente quisesse.

Dê três nomes a cada idioma

Esta é a parte chata, e é onde as pessoas travam. Cada locale precisa de três identificadores, porque a URL, o navegador e o Ghost não falam o mesmo dialeto.

1. Um código de URL. Minúsculo, com hífen, chato: en-us, pt-br, ja-jp. Este é o primeiro segmento do path (/pt-br/articles/…). Mantenha estável. Você vai colar isso em rotas, sitemaps e no seu próprio cérebro.
2. Uma tag BCP-47. É o que vai em <html lang="…"> e hreflang. Normalmente parece en-US ou pt-BR. Espanhol latino-americano é o estranho: não tem um país só, então es-419 é o código honesto mesmo se a URL diz es-la. Aqui está a lista de todas as tags BCP: Language tags on Wikipedia.
3. Uma tag interna do Ghost. O Ghost não tem campo de locale num post, então a gente finge um com uma tag. Eu uso #lang-en-us, #lang-pt-br, e por aí. Marque-as como internal no Ghost para não aparecerem como chips fofos no artigo. No editor você digita o nome com #. Em rotas e filtros você vai ver o slug do Ghost: #lang-pt-br vira hash-lang-pt-br. Mesma tag, duas grafias. Quando você sabe disso, o resto da sintaxe de filtro do Ghost para de parecer assombrada.

Você pode guardar labels extras na lista também — um nome longo em inglês para telas de settings, um nome nativo (Português, 日本語) para o seletor de idioma, etc.

Um exemplo pequenininho de uma linha nessa lista:

{
  code: "pt-br",        // URL: /pt-br/
  bcp47: "pt-BR",       // <html lang="pt-BR">
  tagName: "#lang-pt-br",
  tagSlug: "hash-lang-pt-br",
  label: "Brazilian Portuguese",
  nativeLabel: "Português",
}

Repita esse objeto para cada idioma, mais um DEFAULT_LOCALE apontando para o código padrão. Coloque num módulo, num JSON, num YAML — o que o seu stack já usa. O formato não é o ponto. O ponto é que nada mais inventa uma grafia nova.

Crie as tags no Ghost uma vez

Abra Ghost Admin → Tags e crie essas tags #lang-* como tags internas. Faça na mão se você só tem dois idiomas.

Enquanto estiver lá, decida como as traduções da mesma história se encontram. Eu uso uma segunda tag interna, #translation-{some-stable-name}. O nome estável é só um slug que você escolhe: how-i-learned-to-stop-worrying, ou translation-architecture. Cada versão de idioma dessa história leva a mesma tag de grupo, mais a própria #lang-*. O idioma diz “este post é português.” A tag de grupo diz “este post é o irmão em português daquele em inglês.”

Você não precisa da tag de grupo no primeiro dia. Precisa no momento em que quiser um link “leia isto em outro idioma”. Se não quiser esse widget, pule.

Crie os grupos de newsletter

O Ghost já sabe enviar e-mail para as pessoas. Ele não sabe que /pt-br/ deveria entrar numa lista em português. Fora da caixa você ganha uma newsletter. Tudo bem para um blog de um idioma só. Para este setup, você quer uma newsletter por idioma, com nome que você ainda reconheça às 1 da manhã.

Abra Ghost Admin → Settings → Newsletters e crie uma lista para cada linha da sua tabela de locales. Eu nomeei as minhas pelo código da URL, alto e óbvio: Newsletter EN-US, Newsletter PT-BR, e por aí. O nome é para você. O Ghost também te entrega um id — uma string longa e esquisita. Você vai precisar desse id depois, no formulário de inscrição. Guarde um mapa pequeno ao lado da lista de locales:

{
  "en-us": "the-ghost-id-for-english",
  "pt-br": "the-ghost-id-for-portuguese",
}

Copie esses ids para o mapa depois de criar as listas. Mesma ideia das tags: faça uma vez, depois pare de inventar nomes.

Alguns hábitos que poupam dor:

• Nomes estáveis. Se você renomear Newsletter PT-BR para Novidades no ano que vem, mantenha uma chave no seu mapa que ainda diga pt-br. O locale da URL é o lookup, não o título bonito.
• Um idioma por envio. Quando você publica a versão em português de um post, anexe a newsletter em português. Anexe a lista em inglês naquele post e os inscritos em português recebem um idioma que não pediram. Não tem guardrail. Confira duas vezes antes de apertar publish. Você lê o que posta antes de postar, né?

Se você ainda não está enviando e-mails, pule esta parte. As tags e a lista de locales continuam funcionando. Adicione as newsletters na semana em que você realmente quiser um botão de enviar. Só não deixe crescer uma quinta lista sem documentação chamada “Newsletter” porque o Ghost te ofereceu um padrão.

Faça da lista a lei

Depois disso, a regra é social, não técnica: se um locale novo aparecer, ele aparece primeiro na lista. Aí você gera rotas, strings do tema, newsletters e tags de idioma a partir dela. Se você se pegar digitando ja-jp num template porque “é só um lugar,” é assim que a quinta cópia nasce.

Isso é o setup inteiro. Uma tabela curta de idiomas, três nomes cada, tags no Ghost, uma newsletter por locale, um padrão. Tudo nas próximas seções é só essa lista aparecendo no tema, nas URLs de artigo e no formulário de inscrição.

As três camadas

flowchart TB
  subgraph templates [Template i18n]
    json[locale JSON dictionaries]
    build[compile to Handlebars]
    partials[ui helper and nav]
    block[locale contentFor stamp]
    json --> build --> partials
    block --> partials
  end
  subgraph articles [Article translations]
    tags["hash-lang-* plus hash-translation-*"]
    collections[Ghost collections]
    mapBuild[sidecar builds JSON map]
    jsonMap["/i18n/article-translations.json"]
    ui[nav picker and post switcher]
    tags --> collections
    tags --> mapBuild --> jsonMap --> ui
  end
  subgraph newsletters [Locale newsletters]
    ghostNL[one Ghost newsletter per locale]
    nlJson[locale to newsletter id]
    form[Members subscribe form]
    ghostNL --> nlJson --> form
  end

Leia da esquerda para a direita, não como um pipeline. Mudar o label do botão Subscribe nunca mexe no mapa de artigos. Publicar um rascunho em japonês nunca reescreve o dicionário em inglês. Inscrever-se em Newsletter PT-BR não cria um grupo de tradução.

Camada 1 é o tema, Camada 2 são os posts (mais um servidor pequeno que imprime o mapa de irmãos), Camada 3 é o formulário de inscrição.

Camada 1 — traduzir o template

A versão simples

O tema precisa dizer “Subscribe” em quatro idiomas. O Ghost não vai escolher a string a partir da URL. Então você guarda um dicionário JSON por locale, compila em Handlebars e carimba o locale atual em cada página antes do layout renderizar.

Não misture isso com o locales/en.json (ou pt-BR.json, …) do próprio Ghost. Esses arquivos alimentam {{t}}, que ainda segue o idioma do site no Admin. Os seus dicionários alimentam um helper compilado que segue a URL (ou a tag #lang-* do post). Duas pastas, dois trabalhos.

Carimbar o locale

As rotas customizadas do Ghost podem apontar uma URL para um template nomeado. É por isso que cada home de locale é um wrapper pequenininho: home-en-us.hbs não duplica a homepage. Só diz “esta página é en-us / en-US” e depois inclui home.hbs. O índice de artigos e a página about fazem o mesmo (index-pt-br.hbs → index.hbs). Você precisa desses wrappers porque o campo template: do routes.yaml é como o Ghost escolhe o arquivo — ele não infere o locale a partir do path sozinho.

Esse carimbo é um bloco content do Handlebars:

{{#contentFor 'locale'}}pt-br{{/contentFor}}
{{#contentFor 'bcp47'}}pt-BR{{/contentFor}}
{{!< index}}

Artigos não podem usar um nome de template por locale desse jeito — todos usam post.hbs. Em vez disso, um partial pequeno percorre as tags internas do post. Viu #lang-ja-jp? A página vira japonês, mesmo o arquivo de template sendo o mesmo.

O layout copia isso para algo que o navegador consegue ler, e também espia o primeiro segmento do path, para <html lang="…"> bater com /ja-jp/….

Bater em / não escolhe um idioma para o layout. Uma página de detecção pequenininha olha navigator.languages e redireciona para /en-us/, /ja-jp/, /pt-br/ ou /es-la/. As homes de verdade todas vivem sob um prefixo.

Onde as palavras moram

O copy editável mora num JSON por locale, ao lado do tema:

themes/your-theme/locales/en-us.json
themes/your-theme/locales/ja-jp.json
themes/your-theme/locales/pt-br.json
themes/your-theme/locales/es-la.json

Uma chave fica assim em inglês:

{
  "Subscribe": "SUBSCRIBE_TO_FEED",
  "No posts": "NO_SIGNAL"
}

O arquivo em português tem as mesmas keys, valores diferentes. Templates nunca hard-codam essas frases. Eles pedem uma key:

{{> "ui" key="Subscribe"}}

Por que compilamos em vez de buscar em runtime

Você já conheceu {{t}} na seção anterior: ele não consegue seguir /pt-br/. Você poderia buscar JSON no navegador, mas aí o primeiro paint piscava inglês, os buscadores não veriam o nav em português, e cada template ganharia um monte de JavaScript. Ruim para SEO, pior no first load, e simplesmente feio.

Então você compila. Um build pequeno lê os seus dicionários e escreve Handlebars que já contém cada idioma: em páginas comuns, casa o bloco de locale ({{#match (block "locale") "pt-br"}}…); em posts, casa a tag #lang-*. O template ainda parece {{> "ui" key="Subscribe"}}. Por baixo é uma árvore if / else if gerada.

Isso significa que toda vez que você adiciona copy/texto novo no tema, você rebuilda e depois recarrega o tema no Ghost. Eu sei que é chato, mas você não deveria estar adicionando texto novo no tema com tanta frequência mesmo. (não é um post.)

Trate aquele partial gerado como output, não como um arquivo que você esculpe. Se você editar o helper compilado na mão, o próximo build vai destruir a sua tarde com educação.

Um detalhe prático: mantenha o helper compilado compacto — sem newlines extras dentro da string. Você vai jogar isso em aria-label e placeholder, e whitespace do Handlebars em atributos é um presente que você não quer.

Exemplo: renomear um botão

Você quer que o CTA de subscribe em inglês continue OPEN_CHANNEL, mas o português deve ler ABRIR_CANAL.

1. Edite o arquivo de locale em português na key que o template já usa.
2. Rode o passo de compile para o helper Handlebars pegar a string nova.
3. Recarregue o tema no Ghost.

Você não mexeu em posts do Ghost. Você não mexeu em newsletters. Um leitor em /pt-br/ vê o label novo; /en-us/ não.

Camada 2 — traduzir o artigo

A versão simples

Um artigo não é uma entrada com quatro corpos. São quatro posts Ghost (ou quantos idiomas você realmente escreveu). Uma tag de idioma coloca cada post na URL de índice certa. Uma tag de tradução compartilhada diz ao site que são a mesma história. Um JSON map pequeno, construído a partir dessas tags, alimenta os links “leia em outro idioma”. Isso mantém cada URL num idioma só, o que buscadores realmente conseguem ranquear.

Tags de idioma e URLs

Collections do Ghost (em routes.yaml) decidem quais posts aparecem sob qual path. Um locale que não é o padrão é um filtro de tag direto. O locale padrão é o balde do que sobrou: tudo que não está tagged com os outros idiomas. Se você filtrar inglês como tag:hash-lang-en-us, posts antigos sem tag somem do índice. O filtro invertido é o ponto inteiro.

collections:
  /pt-br/articles/:
    permalink: /pt-br/articles/{slug}/
    template: index-pt-br
    filter: tag:hash-lang-pt-br
  /en-us/articles/:
    permalink: /en-us/articles/{slug}/
    template: index-en-us
    filter: tag:-hash-lang-ja-jp+tag:-hash-lang-pt-br+tag:-hash-lang-es-la

A mesma ideia para japonês e espanhol: tag:hash-lang-ja-jp, tag:hash-lang-es-la. Repita uma collection por locale.

Ainda assim a gente cola #lang-en-us em cada peça em inglês para o tema, o hreflang e o mapa verem o locale do mesmo jeito que veem japonês. O filtro invertido é só como o índice continua gentil com os retardatários.

Tags públicas como Architecture são tópicos. São chips visíveis. Não são idiomas. Um post pode ser #lang-pt-br + Architecture + #translation-translation-architecture ao mesmo tempo.

Traduza o slug junto com o artigo. Não reutilize o path em inglês com -ja / -pt / -es parafusado. Você quer que a URL reflita o idioma e o conteúdo, é importante para SEO:

• Inglês: i-made-ghost-work-with-multiple-languages
• Japonês: ghost-wo-tagengo-ni-shita-hanashi
• Português: fiz-o-ghost-funcionar-com-varios-idiomas
• Espanhol: hice-que-ghost-funcionara-en-varios-idiomas

As tags ainda são o que o software usa para ligar irmãos. O slug é para humanos e busca.

Exemplo: uma história, quatro posts

Sem a tag de idioma, o corpo em japonês vazaria para o índice em inglês (porque inglês é “tudo que não é ja/pt/es”). Sem a tag de grupo, você teria quatro posts sem relação: o picker te mandaria para a home /ja-jp/ em vez do irmão em japonês.

Pages também podem entrar neste mapa se carregarem as duas tags. About muitas vezes é uma rota de locale (/pt-br/about/) em vez de um post de collection, mas o mapa não liga — ele varre posts e pages publicados.

O mapa de tradução

Alguma coisa tem que percorrer o conteúdo publicado e manter um post só quando as duas tags existem. Drafts ficam fora do mapa público. Um post em inglês publicado com tag de idioma mas sem tag de grupo também é invisível para o switcher (ainda aparece em /en-us/articles/).

Você serve o resultado como JSON que o tema pode fetch():

GET /i18n/article-translations.json

Um exemplo aparado para este artigo:

{
  "updated_at": "2026-09-19T00:00:00.000Z",
  "by_url": {
    "https://example.com/en-us/articles/i-made-ghost-work-with-multiple-languages/": "translation-architecture",
    "https://example.com/ja-jp/articles/ghost-wo-tagengo-ni-shita-hanashi/": "translation-architecture"
  },
  "groups": {
    "translation-architecture": {
      "en-us": {
        "url": "/en-us/articles/i-made-ghost-work-with-multiple-languages/",
        "title": "I made Ghost work with multiple languages"
      },
      "ja-jp": {
        "url": "/ja-jp/articles/ghost-wo-tagengo-ni-shita-hanashi/",
        "title": "Ghost を多言語にした話"
      }
    }
  }
}

by_url é “eu estou nesta URL absoluta; em que grupo eu estou?” groups é “nesse grupo, qual é o path e o title para japonês?” Paths em groups são relativos ao site; keys em by_url são absolutas, incluindo scheme e host.

Não olhe window.location.href. Query strings, hashes, uma trailing slash faltando, ou www vs host nu vão errar. Monte uma key a partir de origin + pathname e force uma / no final para bater com o que o Ghost guardou.

O Ghost não vai construir este arquivo para você. Eu não queria ficar montando na mão, então fiz um servidor/app pequeno para fazer isso por mim.

Quem usa isso

Duas coisas, ambas a partir das mesmas tags:

1. Pessoas. Os links “leia em outro idioma” (e o picker do header num post) fazem fetch do JSON e apontam para as URLs irmãs. Sem irmão? Joga na home ou na lista de artigos daquele idioma.
2. Google. Coloque hreflang no <head> da página para os buscadores saberem que as quatro URLs são a mesma história. O Ghost consegue listar esses posts com {{#get "posts"}} filtrado pela tag de tradução. Use limit="100", não limit="all" — o Ghost 6 ignora “all” mesmo assim.

Se o switcher estiver em branco:

• O irmão ainda é draft?
• Os dois posts receberam a mesma tag de grupo, e exatamente uma #lang-* cada?
• Você olhou origin + pathname (trailing slash), não o href cru?
• O sidecar está usando uma API que realmente vê tags internas? (Isso é a próxima seção.)

Um servidorzinho Python para o mapa

Escrever e manter este mapa na mão é um saco, então eu rodo um processo Python pequeno ao lado do Ghost.

O Ghost tem duas APIs. A Content API pública esconde tags internas (#lang-*, #translation-*), então o seu mapa voltaria vazio. Use a Admin API. Faça uma Custom integration, copie a Admin key, deixe no servidor — nunca no tema ou no navegador.

Copie a Admin API key em Ghost Admin → Integrations → a sua integration. Tem que ser exatamente duas partes: um key id, dois-pontos, depois um secret hex. O JWT abaixo faz split(":", 1) e bytes.fromhex na segunda metade. Se você montar a string a partir do JSON da Admin API, olhe api_keys onde type é admin. Às vezes secret já é id:hex. Se você prefixar id de novo, ficam três pedaços, fromhex morre com non-hexadecimal number found, e o processo do mapa parece “no ar” servindo nada. Conte os dois-pontos. Dois segmentos. Hex à direita.

O trabalho do servidor: pedir à Admin posts e pages publicados, ficar com as linhas que têm as duas tags, cuspir o JSON acima. Só biblioteca padrão. Docker para ele sentar na rede do Ghost.

Env vars:

• GHOST_URL — como este container alcança o Ghost (muitas vezes http://ghost:2368).
• SITE_URL — o origin público que visitantes veem, sem trailing slash (https://your-blog.example). As keys do mapa são montadas a partir disto, não de GHOST_URL.
• ADMIN_API_KEY — Ghost Admin API key, id:secret. Não a Content API key.

Cada request pode reconstruir o mapa. Isso é lento-e-honesto num blog pessoal. Cache na memória por um minuto se você crescer e, se ainda quiser mais performance/refreshes mais rápidos, use os Webhooks do Ghost para reconstruir e cachear.

app.py

Jogue isto como app.py. Só biblioteca padrão — Admin JWT de curta duração via hmac, sem pip install.

#!/usr/bin/env python3
from __future__ import annotations

import base64
import hashlib
import hmac
import json
import os
import time
import urllib.parse
import urllib.request
from datetime import datetime, timezone
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

GHOST_URL = os.environ["GHOST_URL"].rstrip("/")
SITE_URL = os.environ.get("SITE_URL", GHOST_URL).rstrip("/")
ADMIN_API_KEY = os.environ["ADMIN_API_KEY"]
PORT = int(os.environ.get("PORT", "8080"))

LANG_PREFIX = "hash-lang-"
GROUP_PREFIX = "hash-translation-"


def b64url(data: bytes) -> str:
    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()


def admin_token() -> str:
    # ADMIN_API_KEY is "id:hexsecret". If `secret` from the Admin API already
    # includes a colon, it is the full key — do not prefix the id again.
    key_id, secret_hex = ADMIN_API_KEY.split(":", 1)
    now = int(time.time())
    header = b64url(
        json.dumps(
            {"alg": "HS256", "typ": "JWT", "kid": key_id},
            separators=(",", ":"),
        ).encode()
    )
    payload = b64url(
        json.dumps(
            {"iat": now, "exp": now + 300, "aud": "/admin/"},
            separators=(",", ":"),
        ).encode()
    )
    signing = f"{header}.{payload}".encode()
    sig = b64url(hmac.new(bytes.fromhex(secret_hex), signing, hashlib.sha256).digest())
    return f"{header}.{payload}.{sig}"


def fetch_all(kind: str) -> list[dict]:
    items: list[dict] = []
    page = 1
    while True:
        query = urllib.parse.urlencode(
            {
                "filter": "status:published",
                "include": "tags",
                "fields": "id,title,slug,url",
                "limit": "50",
                "page": str(page),
            }
        )
        url = f"{GHOST_URL}/ghost/api/admin/{kind}/?{query}"
        req = urllib.request.Request(
            url,
            headers={
                "Accept-Version": "v6.0",
                "Authorization": f"Ghost {admin_token()}",
            },
        )
        with urllib.request.urlopen(req, timeout=30) as response:
            payload = json.loads(response.read().decode())
        items.extend(payload.get(kind, []))
        pages = payload.get("meta", {}).get("pagination", {}).get("pages", 1)
        if page >= pages:
            break
        page += 1
    return items


def locale_and_group(tags: list[dict]) -> tuple[str | None, str | None]:
    locale = group = None
    for tag in tags or []:
        slug = tag.get("slug") or ""
        if slug.startswith(LANG_PREFIX):
            locale = slug.removeprefix(LANG_PREFIX)
        if slug.startswith(GROUP_PREFIX):
            group = slug.removeprefix(GROUP_PREFIX)
    return locale, group


def build_map(entries: list[dict]) -> dict:
    groups: dict = {}
    by_url: dict = {}
    for entry in entries:
        locale, group = locale_and_group(entry.get("tags") or [])
        if not locale or not group:
            continue
        raw = entry.get("url") or f"/{locale}/articles/{entry['slug']}/"
        path = (
            urllib.parse.urlparse(raw).path
            if raw.startswith("http")
            else (raw if raw.startswith("/") else f"/{raw}")
        )
        if not path.endswith("/"):
            path = f"{path}/"
        groups.setdefault(group, {})[locale] = {
            "url": path,
            "title": entry.get("title"),
        }
        by_url[f"{SITE_URL}{path}"] = group
    return {
        "updated_at": datetime.now(timezone.utc).isoformat(),
        "by_url": by_url,
        "groups": groups,
    }


class Handler(BaseHTTPRequestHandler):
    def do_GET(self) -> None:
        path = self.path.split("?", 1)[0]
        if path == "/health":
            body = b'{"ok":true}'
        elif path == "/article-translations.json":
            body = json.dumps(
                build_map(fetch_all("posts") + fetch_all("pages"))
            ).encode()
        else:
            self.send_error(404)
            return
        self.send_response(200)
        self.send_header("Content-Type", "application/json; charset=utf-8")
        self.send_header("Cache-Control", "no-store")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def log_message(self, fmt: str, *args) -> None:
        print(fmt % args)


if __name__ == "__main__":
    print(f"translation map on :{PORT}")
    ThreadingHTTPServer(("0.0.0.0", PORT), Handler).serve_forever()

Docker

Dockerfile:

FROM python:3.12-slim
WORKDIR /app
COPY app.py .
EXPOSE 8080
CMD ["python", "-u", "app.py"]

Ao lado do Ghost no Compose:

services:
  ghost:
    # your existing Ghost service

  translation-map:
    build: ./translation-map
    environment:
      GHOST_URL: http://ghost:2368
      SITE_URL: https://your-blog.example
      ADMIN_API_KEY: ${GHOST_ADMIN_API_KEY}
    depends_on:
      - ghost

PS: Isto não é um setup de produção completo, mas você pode ajustar para as suas necessidades. Eu recomendo ler as docs do Ghost para isso: [https://docs.ghost.org/install/docker](Docker Ghost Setup) e [https://docs.ghost.org/hosting](Docker Hosting Guide)

Ligar no tema

No layout:

<script>
  window.__articleTranslationsUrl = '{{@site.url}}/i18n/article-translations.json';
</script>

Numa página de post, fetch essa URL, depois:

const path = location.pathname.endsWith('/') ? location.pathname : `${location.pathname}/`;
const canonical = `${location.origin}${path}`;
const groupId = map.by_url[canonical];
const siblings = groupId ? map.groups[groupId] : null;

Desenhe links para cada locale cujo url não é o path atual. O seletor de idioma faz o mesmo lookup para o locale que o leitor acabou de escolher. Sem irmãos? Cai para /{locale}/ ou /{locale}/articles/.

Camada 3 — ligar o formulário da newsletter

Você já criou uma newsletter Ghost por idioma e copiou os ids. Esta camada é só como o formulário escolhe o id certo, e como você anexa uma lista quando publica.

Ghost Members faz o signup. Você dá um id para o formulário:

<form data-members-form="subscribe">
  <label>
    Email
    <input data-members-email type="email" required autocomplete="email" />
  </label>
  <button type="submit">Subscribe</button>
</form>

Coloque o mapa locale → id onde o tema consegue ler (um JSON estático no tema, ou um script inline pequenininho — não a Admin API a partir do navegador). Depois, a partir do primeiro segmento do path, defina o atributo que o Ghost realmente liga:

const locale = location.pathname.split('/').filter(Boolean)[0]; // "pt-br"
form.setAttribute('data-members-newsletter', newsletterIds[locale]);

Um visitante em /pt-br/ entra em Newsletter PT-BR. Na tela de account, liste cada newsletter ativa como checkboxes para bilíngues poderem entrar em mais de uma.

Quando você publica, anexe aquele post à lista correspondente. A versão em inglês → Newsletter EN-US. A versão em português → Newsletter PT-BR. Um draft sem newsletter anexada não manda e-mail para ninguém. Lista errada, idioma errado na caixa de entrada, não tem guardrail aqui, então não cague.

Um passo a passo: publicar este texto em quatro idiomas

Suponha que este artigo é a fonte em inglês.

Inglês. Crie um post. Título e corpo em en-US. Slug i-made-ghost-work-with-multiple-languages. Tags: #lang-en-us, #translation-translation-architecture, mais uma tag pública de tópico se você quiser um chip. No publish, atribua Newsletter EN-US. Aparece em /en-us/articles/i-made-ghost-work-with-multiple-languages/. O template é inglês por causa da tag de idioma. O switcher fica escondido até existir um irmão.

Japonês. Um post novo (não um segundo corpo no inglês). Traduza título, excerpt, HTML, e o slug. Mantenha código no corpo, hrefs e nomes de produto. Slug ghost-wo-tagengo-ni-shita-hanashi. Tags: #lang-ja-jp e a mesma #translation-translation-architecture. Atribua Newsletter JA-JP quando publicar. URL: /ja-jp/articles/ghost-wo-tagengo-ni-shita-hanashi/.

Repita para português (fiz-o-ghost-funcionar-com-varios-idiomas / #lang-pt-br / Newsletter PT-BR) e espanhol (hice-que-ghost-funcionara-en-varios-idiomas / #lang-es-la / Newsletter ES-LA).

Recarregue a página em inglês. O widget deve oferecer 日本語 / Português / Español. O picker do header na URL em inglês pula para o irmão em japonês em vez da home em japonês. Buscadores veem hreflang a partir da query de tag do Ghost. Um leitor que se inscreveu em /es-la/ recebe o envio em espanhol, não quatro e-mails da mesma história.

Se você pular a tag de grupo no espanhol, o espanhol ainda vive em /es-la/articles/…, mas as outras três páginas não vão linkar para ele. Se pular a tag de idioma no espanhol, ele pode aparecer no índice em inglês. Se pular a newsletter, o archive ainda funciona; a lista não envia.

Checklist

Para cada site Ghost

1. Lista de locales com três nomes cada, mais um padrão.
2. Tags internas #lang-* no Ghost (e #translation-* quando você quiser irmãos).
3. Uma newsletter por locale; copie os ids para um mapa que o tema consegue ler.
4. Collections em routes.yaml (filtro invertido no locale padrão) e templates wrapper que carimbam locale / bcp47.
5. Dicionários JSON + passo de compile para o helper ui. Deixe o locales/en.json do próprio Ghost para {{t}} se você ainda usar.
6. Sidecar na Admin API; faça proxy de /i18n/article-translations.json no seu origin público. Confirme que a Admin key é id:hex (duas partes), não um id:id:hex duplicado.
7. Se o routes.yaml aponta / para locale-detect, ative o tema custom antes de tratar / como healthcheck.

Se você quiser adicionar mais idiomas

Lista de locales → tag #lang-* → newsletter + id → JSON de locale + compile → collection + template wrapper → ensine ao mapa o prefixo hash-lang-* novo.

Todo artigo

1. Um post Ghost por locale — nunca quatro idiomas num corpo só.
2. Exatamente uma tag #lang-* por post.
3. A mesma #translation-{group-id} em cada irmão que você quer ligado.
4. Tags públicas só para tópicos.
5. Traduza o slug junto com o artigo (não english-slug-ja).
6. Anexe Newsletter {LOCALE} no publish se aquela versão deve enviar e-mail.
7. Recarregue o post depois de publicar um irmão e confira origin + pathname contra by_url.