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.