Come ho generato una serie di mappe di viaggio in cinese senza browser né chiave API

Mentre pianificavo un viaggio di quattro giorni a Hong Kong, volevo qualcosa di semplice: una mappa chiara per ogni tappa, etichettata in cinese semplificato. Non una mappa in inglese con un segnaposto appiccicato sopra, né un muro di link. Dodici luoghi — l'hotel, i musei, l'Ocean Park, la tramvia del Peak, l'aeroporto — ciascuno come uno screenshot pulito e a sé stante da inserire in un opuscolo stampabile.

Così ho chiesto a Claude Code, in esecuzione in una sessione web isolata, di crearle. Quella che pensavo fosse una commissione da cinque minuti si è trasformata in una breve escursione tra i motivi per cui "una mappa di Hong Kong, in cinese" è più difficile di quanto sembri — incluso un sistema di coordinate che esiste apposta per rendere questo genere di cose più difficile.

Nessun browser, nessuna chiave API

L'approccio ovvio — aprire un sito di mappe, cambiare la lingua in cinese, fare uno screenshot di ogni luogo — era fuori discussione per due motivi. La sessione non aveva un browser da pilotare, e le comode API per mappe statiche vogliono tutte una chiave a pagamento. Quella deviazione si è rivelata un pregio, non un difetto. Google e OpenStreetMap etichettano Hong Kong in modo bilingue o con l'inglese in primo piano; per etichette genuinamente in cinese serve un fornitore cinese. La risposta erano le tile di mappa di AutoNavi (高德), che rendono Hong Kong con nomi in cinese semplificato — 海洋公园, 太平山顶, 尖沙咀 — gli stessi nomi che vedrai sui cartelli e nelle app una volta atterrato. Il piano: scaricare le tile di mappa grezze da 256×256 e assemblare ogni immagine a mano con Pillow di Python.

Il sistema di coordinate di cui nessuno ti avverte

Ecco l'intoppo che si è mangiato un'ora. I fornitori di mappe cinesi sono obbligati per legge a usare GCJ-02, un sistema di coordinate offuscato — colloquialmente "coordinate marziane" — che applica un offset deliberato e non lineare alla vera latitudine e longitudine WGS-84. Traccia una coordinata GPS reale direttamente su una mappa di base cinese e il tuo segnaposto finisce a qualche centinaio di metri di distanza: nell'edificio dall'altra parte della strada, o al largo nel porto. L'offset è il punto — un dosso di rallentamento imposto dallo Stato contro i dati geografici precisi.

Quindi ogni coordinata doveva passare attraverso la trasformazione standard WGS-84 → GCJ-02 prima di qualsiasi calcolo sulle tile: spostare il punto centrale nelle coordinate marziane, recuperare le tile attorno a quel punto spostato, poi collocare il marcatore esattamente al centro in modo che si allinei con la mappa di base spostata. Sbaglia e ogni mappa è sottilmente, sicura di sé, sbagliata. Fai bene e nessuno se ne accorge — che è l'intero compito di una mappa.

Disegnare la mappa

Risolto il problema delle coordinate, il resto è idraulica di immagini. Per ogni luogo: capire quali tile coprono l'area, recuperarle e cucirle su una scheda larga 760 pixel, lasciar cadere un segnaposto a goccia al centro, e posare sopra una fascia di intestazione con il nome cinese, un numero d'indice e il giorno del viaggio. Il testo cinese ha bisogno di un font compatibile con CJK; la sandbox forniva WenQuanYi Zen Hei, che se l'è cavata.

Il passaggio che mi è piaciuto di più è stata la verifica. Le coordinate inserite a mano sono esattamente il tipo di cosa plausibile-ma-non-proprio-esatta, così dopo il rendering Claude Code ha riletto le proprie immagini di output e ha controllato ogni segnaposto rispetto agli elementi etichettati sottostanti — il segnaposto del Museo della Scienza è davvero su 香港科学馆, o un isolato più a nord? Un paio di segnaposti sono stati spostati; lo Star Ferry, il capolinea della tramvia del Peak e l'aeroporto sono finiti tutti in pieno centro. Un ciclo costruisci-poi-guardalo, ancora leggermente inedito quando la cosa che guarda è la stessa cosa che ha costruito.

La localizzazione non è traduzione

Le mappe erano la parte facile. Le parole intorno a esse erano il punto in cui è diventata una faccenda umana. Il pubblico legge il mandarino continentale, e l'opuscolo attorno alle mappe era scivolato in sordina nel registro del cantonese di Hong Kong. Avevo descritto l'hotel come 地铁站上盖 — 上盖 è un impeccabile gergo immobiliare di Hong Kong per "costruito proprio sopra la stazione", e quasi opaco per un lettore continentale. È diventato 就在地铁站楼上. Poi 离港 → 返程, 手信 → 伴手礼, e 有得逛 — una costruzione grammaticale cantonese — → 能逛.

Il cibo aveva bisogno del trattamento opposto. 烧味饭, 炖奶, 滑蛋 sono nomi di piatti cantonesi, ma sono i nomi reali sui menu reali, quindi "correggerli" renderebbe l'opuscolo sbagliato. Quelli hanno mantenuto i loro nomi e hanno invece ricevuto glosse in mandarino — 烧味饭（即烧腊饭：叉烧、烧鹅、烧肉饭）. I ristoranti stessi, dopo un giro di feedback, hanno perso del tutto le loro pagine di mappa dedicate: non si naviga verso la cena come si naviga verso l'Ocean Park, quindi sono rimasti come testo nel programma giornaliero e sono usciti dall'indice delle mappe. Niente di tutto ciò è traduzione nel senso da dizionario. È registro, dialetto, e sapere quando una parola è un regionalismo da correggere anziché un nome proprio da lasciare stare.

Cosa ne traggo

Questo atterra dove continuo ad atterrare: il lavoro procede più veloce sui compiti che sono finiti e verificabili. Cucire le tile, applicare una trasformazione di coordinate nota, confermare che un segnaposto sia sulla sua etichetta — ogni passaggio ha una risposta giusta che puoi verificare guardando, il che richiama ciò che trovo nelle ispezioni di sicurezza e negli strumenti di conformità. La deviazione GCJ-02 è quel genere di nozione di dominio noiosa da scoprire e banale da applicare una volta nota — proprio la cosa che vale la pena scaricare altrove.

Il giudizio è rimasto mio: quali dodici luoghi contano come "primari", che i ristoranti non avevano bisogno di mappe, che un lettore di mandarino continentale non dovrebbe dover decifrare 上盖. L'opuscolo finito — dodici mappe in cinese, un programma giorno per giorno e un PDF stampabile — è uscito da una sandbox senza browser e senza chiave API. Un anno fa non avrei indovinato che quella fosse la versione facile.