Multilingual Support

MapToPoster supports displaying city and country names in any language, including non-Latin scripts like Japanese, Arabic, Korean, Thai, Chinese, and more. Fonts are automatically downloaded from Google Fonts and cached locally.

Overview

The multilingual system provides:

Custom display names for city and country in any language
Automatic font downloading from Google Fonts catalog
Local font caching to avoid repeated downloads
Script detection for proper typography (Latin vs. non-Latin)
Fallback handling for missing fonts

Basic Usage

Display Names

Use --display-city and --display-country to override the displayed text:

python create_map_poster.py \
  -c "Tokyo" \
  -C "Japan" \
  -dc "東京" \
  -dC "日本"

The -c and -C flags are still required for geocoding (finding the city location). The display flags only change what appears on the poster.

Custom Fonts

Specify any font from Google Fonts using --font-family:

python create_map_poster.py \
  -c "Tokyo" \
  -C "Japan" \
  -dc "東京" \
  -dC "日本" \
  --font-family "Noto Sans JP"

The font is automatically:

Downloaded from Google Fonts API
Cached in fonts/cache/
Loaded for text rendering

Language Examples

python create_map_poster.py \
  -c "Tokyo" -C "Japan" \
  -dc "東京" -dC "日本" \
  --font-family "Noto Sans JP" \
  -t japanese_ink

Recommended Fonts:

Noto Sans JP (modern, clean)
Noto Serif JP (traditional, elegant)
M PLUS Rounded 1c (rounded, friendly)
Zen Kaku Gothic New (contemporary)

Other Cities:

# Osaka (大阪)
python create_map_poster.py -c "Osaka" -C "Japan" -dc "大阪" -dC "日本" --font-family "Noto Sans JP"

# Kyoto (京都)
python create_map_poster.py -c "Kyoto" -C "Japan" -dc "京都" -dC "日本" --font-family "Noto Serif JP"

python create_map_poster.py \
  -c "Seoul" -C "South Korea" \
  -dc "서울" -dC "대한민국" \
  --font-family "Noto Sans KR" \
  -t midnight_blue

Recommended Fonts:

Noto Sans KR (clean, modern)
Noto Serif KR (traditional)
Black Han Sans (bold display)
Nanum Gothic (versatile)

Other Cities:

# Busan (부산)
python create_map_poster.py -c "Busan" -C "South Korea" -dc "부산" -dC "대한민국" --font-family "Noto Sans KR"

python create_map_poster.py \
  -c "Dubai" -C "UAE" \
  -dc "دبي" -dC "الإمارات" \
  --font-family "Cairo" \
  -t terracotta

Recommended Fonts:

Cairo (modern, geometric)
Amiri (traditional, classical)
Tajawal (clean, versatile)
Almarai (contemporary)

Other Cities:

# Riyadh (الرياض)
python create_map_poster.py -c "Riyadh" -C "Saudi Arabia" -dc "الرياض" -dC "السعودية" --font-family "Cairo"

# Marrakech (مراكش)
python create_map_poster.py -c "Marrakech" -C "Morocco" -dc "مراكش" -dC "المغرب" --font-family "Amiri"

# Simplified Chinese
python create_map_poster.py \
  -c "Beijing" -C "China" \
  -dc "北京" -dC "中国" \
  --font-family "Noto Sans SC"

# Traditional Chinese
python create_map_poster.py \
  -c "Taipei" -C "Taiwan" \
  -dc "台北" -dC "台灣" \
  --font-family "Noto Sans TC"

Recommended Fonts:

Noto Sans SC (Simplified, modern)
Noto Sans TC (Traditional, modern)
Noto Serif SC (Simplified, serif)
Noto Serif TC (Traditional, serif)
ZCOOL XiaoWei (stylized)

Other Cities:

# Shanghai (上海)
python create_map_poster.py -c "Shanghai" -C "China" -dc "上海" -dC "中国" --font-family "Noto Sans SC"

# Hong Kong (香港)
python create_map_poster.py -c "Hong Kong" -C "China" -dc "香港" -dC "中國" --font-family "Noto Sans TC"

python create_map_poster.py \
  -c "Bangkok" -C "Thailand" \
  -dc "กรุงเทพมหานคร" -dC "ประเทศไทย" \
  --font-family "Noto Sans Thai" \
  -t sunset

Recommended Fonts:

Noto Sans Thai
Noto Serif Thai
Kanit (modern)
Prompt (clean)

Other Cities:

# Chiang Mai (เชียงใหม่)
python create_map_poster.py -c "Chiang Mai" -C "Thailand" -dc "เชียงใหม่" -dC "ประเทศไทย" --font-family "Noto Sans Thai"

python create_map_poster.py \
  -c "Phnom Penh" -C "Cambodia" \
  -dc "ភ្នំពេញ" -dC "កម្ពុជា" \
  --font-family "Noto Sans Khmer"

Recommended Fonts:

Noto Sans Khmer
Noto Serif Khmer
Battambang

python create_map_poster.py \
  -c "Athens" -C "Greece" \
  -dc "Αθήνα" -dC "Ελλάδα" \
  --font-family "Noto Sans"

Other Cities:

# Thessaloniki (Θεσσαλονίκη)
python create_map_poster.py -c "Thessaloniki" -C "Greece" -dc "Θεσσαλονίκη" -dC "Ελλάδα" --font-family "Noto Sans"

python create_map_poster.py \
  -c "Tel Aviv" -C "Israel" \
  -dc "תל אביב" -dC "ישראל" \
  --font-family "Noto Sans Hebrew"

Recommended Fonts:

Noto Sans Hebrew
Noto Serif Hebrew
Heebo (modern)

python create_map_poster.py \
  -c "Moscow" -C "Russia" \
  -dc "Москва" -dC "Россия" \
  --font-family "Noto Sans"

Other Cities:

# Saint Petersburg (Санкт-Петербург)
python create_map_poster.py -c "Saint Petersburg" -C "Russia" -dc "Санкт-Петербург" -dC "Россия" --font-family "Noto Sans"

Typography Behavior

Script Detection

The tool automatically detects whether text is Latin or non-Latin: Latin Scripts (English, French, Spanish, etc.):

Letter spacing applied for elegant aesthetics
Example: “P A R I S” (spaces between letters)

Non-Latin Scripts (Japanese, Arabic, Thai, etc.):

Natural spacing preserved
Example: “東京” (no artificial gaps)

This ensures proper typography for all languages without manual configuration.

Text Positioning

All text is positioned using normalized coordinates:

y=0.14  City name (spaced for Latin, natural for non-Latin)
y=0.125 Decorative line
y=0.10  Country name
y=0.07  Coordinates

Font Management

Automatic Caching

Fonts are cached in fonts/cache/ after first download:

fonts/
├── Roboto-Light.ttf      # Default fonts
├── Roboto-Regular.ttf
├── Roboto-Bold.ttf
└── cache/
    ├── Noto_Sans_JP-Regular.ttf
    ├── Noto_Sans_KR-Regular.ttf
    ├── Cairo-Regular.ttf
    └── ...

Manual Font Installation

You can also manually place fonts in fonts/cache/:

Download .ttf file from Google Fonts
Place in fonts/cache/ directory
Use the font family name with --font-family

Finding Google Fonts

Browse available fonts at fonts.google.com:

Filter by language/script
Copy the font family name
Use exact name with --font-family

Font names are case-sensitive and must match exactly as shown on Google Fonts.

Complete Examples

Japanese with Custom Theme

python create_map_poster.py \
  -c "Tokyo" -C "Japan" \
  -dc "東京" -dC "日本" \
  --font-family "Noto Sans JP" \
  -t japanese_ink \
  -d 15000

Arabic with Multiple Flags

python create_map_poster.py \
  -c "Dubai" -C "UAE" \
  -dc "دبي" -dC "الإمارات" \
  --font-family "Cairo" \
  -t midnight_blue \
  -d 15000 \
  -W 12 -H 16

Korean with All Themes

python create_map_poster.py \
  -c "Seoul" -C "South Korea" \
  -dc "서울" -dC "대한민국" \
  --font-family "Noto Sans KR" \
  --all-themes

Chinese with Custom Coordinates

python create_map_poster.py \
  -c "Beijing" -C "China" \
  -dc "北京" -dC "中国" \
  --font-family "Noto Sans SC" \
  -lat 39.9042 -long 116.4074 \
  -t noir

Troubleshooting

Font not found on Google Fonts

Ensure the font name matches exactly as shown on fonts.google.com. Font names are case-sensitive.

# Correct
--font-family "Noto Sans JP"

# Incorrect
--font-family "noto sans jp"
--font-family "Noto-Sans-JP"

Characters not displaying correctly

Make sure the font you selected supports the script you’re using. Check the font’s supported languages on Google Fonts.For example:

Use “Noto Sans JP” for Japanese (not “Roboto”)
Use “Cairo” for Arabic (not “Open Sans”)
Use “Noto Sans KR” for Korean

Text appears too spaced out

This is normal for Latin scripts. The tool applies letter spacing for aesthetics (“P A R I S”).For non-Latin scripts, spacing is not applied. If you see unwanted spacing in Japanese/Arabic/etc., the tool may be incorrectly detecting the script. File a bug report.

Font download fails

If font downloads fail:

Check your internet connection
Verify the font exists on Google Fonts
Try downloading manually and placing in fonts/cache/
Check the font file name matches the pattern: Font_Name-Regular.ttf

Using system fonts instead of Google Fonts

The tool is designed for Google Fonts integration. To use system fonts:

Copy the .ttf file to fonts/cache/
Use the font family name with --font-family

Note: The tool expects TrueType fonts (.ttf format).

Font Recommendations by Script

Script	Language Examples	Recommended Fonts
Japanese	日本語	Noto Sans JP, Noto Serif JP, M PLUS Rounded 1c
Korean	한국어	Noto Sans KR, Noto Serif KR, Black Han Sans
Chinese (Simp.)	简体中文	Noto Sans SC, Noto Serif SC, ZCOOL XiaoWei
Chinese (Trad.)	繁體中文	Noto Sans TC, Noto Serif TC
Arabic	العربية	Cairo, Amiri, Tajawal, Almarai
Thai	ไทย	Noto Sans Thai, Kanit, Prompt
Hebrew	עברית	Noto Sans Hebrew, Heebo
Greek	Ελληνικά	Noto Sans, Roboto
Cyrillic	Кириллица	Noto Sans, Roboto, Montserrat
Devanagari	देवनागरी	Noto Sans Devanagari, Poppins
Bengali	বাংলা	Noto Sans Bengali, Hind Siliguri
Tamil	தமிழ்	Noto Sans Tamil, Pavanam

Get Started

Usage

Guides

Examples

Overview

Basic Usage

Display Names

Custom Fonts

Language Examples

Typography Behavior

Script Detection

Text Positioning

Font Management

Automatic Caching

Manual Font Installation

Finding Google Fonts

Complete Examples

Japanese with Custom Theme

Arabic with Multiple Flags

Korean with All Themes

Chinese with Custom Coordinates

Troubleshooting

Font Recommendations by Script

Next Steps

Theme Gallery

Advanced Examples

​Overview

​Basic Usage

​Display Names

​Custom Fonts

​Language Examples

​Typography Behavior

​Script Detection

​Text Positioning

​Font Management

​Automatic Caching

​Manual Font Installation

​Finding Google Fonts

​Complete Examples

​Japanese with Custom Theme

​Arabic with Multiple Flags

​Korean with All Themes

​Chinese with Custom Coordinates

​Troubleshooting

​Font Recommendations by Script

​Next Steps

Theme Gallery

Advanced Examples

Overview

Basic Usage

Display Names

Custom Fonts

Language Examples

Typography Behavior

Script Detection

Text Positioning

Font Management

Automatic Caching

Manual Font Installation

Finding Google Fonts

Complete Examples

Japanese with Custom Theme

Arabic with Multiple Flags

Korean with All Themes

Chinese with Custom Coordinates

Troubleshooting

Font Recommendations by Script

Next Steps