LogoفارسیFA

Internationalization and Localization in Django: A Complete Overview

This article explains the concepts of internationalization (i18n) and localization (l10n) in Django. It covers how Django handles translations, date and number formatting, locale definitions, language codes, message files, and format files. It also clarifies key terminology and how Django adapts content to users’ language and cultural preferences.

Django internationalizationDjango localization, i18n, l10n, locale name, language codemessage file, translation string, format file

~3 min read · Updated Mar 15, 2026

Introduction

Modern web applications often need to serve users from different countries, cultures, and language backgrounds. Django provides a powerful and comprehensive framework for internationalization (i18n) and localization (l10n), enabling developers to translate text, format dates and numbers, and adapt content to user preferences.

Django essentially does two things:

  • Allows developers and template authors to mark parts of the application for translation or localization.
  • Uses these markers to present content in the user’s preferred language and format.

Language preferences are typically provided by the browser via the Accept-Language header. Formatting (dates, numbers, etc.) depends on the target locale. Time zone detection, however, requires additional configuration because browsers do not send it automatically.


Internationalization vs Localization

These two terms are often confused, but Django treats them as distinct concepts:

Internationalization (i18n)

Preparing the software for localization. This includes marking strings for translation and structuring the application so it can support multiple languages. This is typically done by developers.

Localization (l10n)

Providing actual translations and locale-specific formats (dates, numbers, etc.). This is usually done by translators.

For deeper reading, see:

  • W3C Web Internationalization FAQ
  • Wikipedia’s article on internationalization
  • GNU gettext documentation

Note: Django’s USE_I18N setting controls translation, even though it affects both internationalization and localization. The name is historical.


Key Terminology

Locale Name

A locale name identifies a specific language or a language-country combination. Formats:

  • ll → language only (e.g., it, es)
  • ll_CC → language + country (e.g., de_AT, pt_BR, sr_Latn)

Rules:

  • Language part → lowercase
  • Country part → uppercase (2 letters) or TitleCase (longer)
  • Separator → underscore

Language Code

Used by browsers in the Accept-Language header. Format is similar to locale names but uses a dash instead of an underscore:

  • it
  • de-at
  • pt-br

Language codes are case-insensitive.


Message File (.po)

A plain-text file containing translation strings and their translated versions for a specific language. Each language has its own .po file.


Translation String

A literal string in your code or templates that can be translated using Django’s translation tools.


Format File

A Python module that defines locale-specific formatting rules for:

  • dates
  • times
  • numbers
  • currency formats

Conclusion

Django’s internationalization and localization framework makes it easy to build applications that adapt to users around the world. By understanding key concepts like locale names, language codes, message files, and translation strings, developers can create flexible, multilingual applications that feel natural to users in any region.

Written & researched by Dr. Shahin Siami

Related Articles

Django Tasks Framework: A Complete Guide to Background Task Execution in Django 6.0

Django 6.0 introduces the Tasks framework, a built‑in system for defining and queuing background work outside the request–response cycle. This article explains how Tasks work, how to configure backends, how to define and enqueue tasks, how context works, and how to integrate third‑party worker systems for production environments.

Continue

Asynchronous Support in Django: A Complete Guide to Async Views, ORM, Middleware, Performance, and Safety

This article explains Django’s asynchronous (async) capabilities, including async views, ASGI support, middleware behavior, async ORM features, performance considerations, handling disconnects, and Django’s async safety protections. It also covers how to use sync_to_async(), async ORM methods, and how to safely run synchronous code in async environments.

Continue

Django System Check Framework: A Complete Guide to Writing, Registering, Running, and Testing System Checks

This article explains Django’s System Check Framework—a powerful mechanism for detecting configuration issues, validating project structure, and ensuring code quality. It covers how checks are executed, how to write custom checks, how messages work, how to register and tag checks, how to extend checks for fields and models, and how to write both unit and integration tests for system checks.

Continue

Django Signals: A Complete Guide to Listening, Connecting, Sending, and Managing Application Events

This article provides a comprehensive explanation of Django’s signal system—an event‑driven mechanism that allows decoupled applications to react to actions occurring elsewhere in the framework. It covers how to define receivers, connect signals, use decorators, handle specific senders, organize signal code, and follow best practices to avoid complexity.

Continue

Understanding Django Settings: Configuration, Environment Management, and Best Practices

This article provides a complete overview of Django’s settings system. It explains how settings files work, how to designate a settings module, how to use settings in your code, how to configure Django manually, how to secure sensitive settings, and how to work with custom default settings. It also covers the role of django.setup() for standalone scripts.

Continue

Serializing and Deserializing Django Objects: A Complete Guide to Django’s Serialization Framework

This article explains Django’s serialization framework, including how to serialize and deserialize model instances, work with subsets of fields, handle inherited models, use different serialization formats (JSON, XML, YAML, JSONL), and understand how relational fields are represented. It also covers DeserializedObject behavior and common pitfalls.

Continue
Previous ArticleNext Article