countrystatecity-translations

Official Python package for 4,724 country-name translations covering 250 countries across 19 languages. Part of the countrystatecity ecosystem.

From offline prototype to production

This package provides a versioned offline snapshot. For regularly updated data, server-side search and filtering, field-selected responses, or managed availability and support, use the Country State City API.

Get a free API key · API docs · Pricing · Migration guide

Keep API keys in server-side environment variables, never in client-side code or source control.

Installation

pip install countrystatecity-translations

Quick Start

from countrystatecity_translations import (
    get_all_translations,
    get_translations_by_country,
    get_translations_by_language,
    get_translation,
    search_translations,
)

# Get all translation entries
translations = get_all_translations()
# [Translation(countryCode="AF", lang="fr", translation="Afghanistan", ...), ...]

# Get all translations for a country (all 19 languages)
de_translations = get_translations_by_country("DE")
# [Translation(countryCode="DE", lang="fr", translation="Allemagne", ...), ...]

# Get all countries translated into a specific language
french = get_translations_by_language("fr")
# [Translation(lang="fr", translation="Afghanistan", ...), ...]

# Lookup a single translation
t = get_translation("DE", "fr")
# Translation(countryCode="DE", countryName="Germany", lang="fr", translation="Allemagne")

# Search translated names
results = search_translations("Allemagne")

Data Model

class Translation(BaseModel):
    countryCode: str  # ISO2 country code (e.g., "DE")
    countryName: str  # English country name (e.g., "Germany")
    lang: str         # Language code (e.g., "fr")
    translation: str  # Translated country name (e.g., "Allemagne")

Supported Languages

API Reference

License

ODbL-1.0 — see LICENSE.

Other Packages in this Ecosystem

Data sourced from countries-states-cities-database.

Made with ❤️ by dr5hn