Command
Runs over the entire source tree of the current directory and pulls out all strings marked for translation. It creates (or updates) a message file in the conf/locale (in the django tree) or locale (for projects and applications) directory.
You must run this command with one of either the --locale, --exclude, or --all options.
Attributes
| Attribute | Type | Description |
|---|---|---|
| help | string | Runs over the entire source tree of the current directory and pulls out all strings marked for translation. It creates (or updates) a message file in the conf/locale (in the django tree) or locale (for projects and applications) directory. |
You must run this command with one of either the --locale, --exclude, or --all options. |
| translatable_file_class | = TranslatableFile | The class used to represent and instantiate translatable files found during the source tree crawl. |
| build_file_class | = BuildFile | The class used to handle the preprocessing and build lifecycle of individual files during message extraction. |
| requires_system_checks | list = [] | A list of system checks that must be performed before the command can be executed; defaults to an empty list. |
| msgmerge_options | list = ["-q", "--backup=none", "--previous", "--update"] | A list of command-line arguments passed to the GNU gettext 'msgmerge' utility for merging PO and POT files. |
| msguniq_options | list = ["--to-code=utf-8"] | A list of command-line arguments passed to the GNU gettext 'msguniq' utility to ensure unique message entries. |
| msgattrib_options | list = ["--no-obsolete"] | A list of command-line arguments passed to the GNU gettext 'msgattrib' utility, typically used to filter or modify message attributes. |
| xgettext_options | list = ["--from-code=UTF-8", "--add-comments=Translators"] | A list of command-line arguments passed to the GNU gettext 'xgettext' utility for extracting strings from source code. |
Constructor
Signature
def Command()
Methods
add_arguments()
@classmethod
def add_arguments(
parser: [CommandParser](../../base/commandparser.md?sid=django_core_management_base_commandparser)
)
Configures the command line argument parser with options for locales, exclusions, domains, file extensions, and gettext behavior.
Parameters
| Name | Type | Description |
|---|---|---|
| parser | [CommandParser](../../base/commandparser.md?sid=django_core_management_base_commandparser) | The argument parser instance to which translation-related arguments will be added. |
handle()
@classmethod
def handle(
*args: tuple,
**options: dict
)
Executes the core logic of the command, including validating settings, identifying target locales, and orchestrating the POT and PO file generation process.
Parameters
| Name | Type | Description |
|---|---|---|
| *args | tuple | Variable length argument list. |
| **options | dict | The parsed command line options used to configure the translation extraction behavior. |
gettext_version()
@classmethod
def gettext_version() - > tuple
Retrieves the version of the installed GNU gettext tools by executing 'xgettext --version'.
Returns
| Type | Description |
|---|---|
tuple | A tuple of integers representing the major, minor, and patch version of gettext. |
settings_available()
@classmethod
def settings_available() - > boolean
Checks if the Django settings are properly configured and accessible for translation processing.
Returns
| Type | Description |
|---|---|
boolean | True if LOCALE_PATHS is accessible in settings, False otherwise. |
build_potfiles()
@classmethod
def build_potfiles() - > list
Build pot files and apply msguniq to them.
Returns
| Type | Description |
|---|---|
list | A list of file paths to the generated and processed .pot files. |
remove_potfiles()
@classmethod
def remove_potfiles()
Deletes existing .pot files from all identified locale paths to ensure a clean build state.
find_files()
@classmethod
def find_files(
root: string
) - > list
Get all files in the given root. Also check that there is a matching locale dir for each file.
Parameters
| Name | Type | Description |
|---|---|---|
| root | string | The directory path to start searching for translatable source files. |
Returns
| Type | Description |
|---|---|
list | A sorted list of TranslatableFile objects representing files to be processed for strings. |
process_files()
@classmethod
def process_files(
file_list: list
)
Group translatable files by locale directory and run pot file build process for each group.
Parameters
| Name | Type | Description |
|---|---|---|
| file_list | list | A list of TranslatableFile objects to be grouped and processed. |
process_locale_dir()
@classmethod
def process_locale_dir(
locale_dir: string,
files: list
)
Extract translatable literals from the specified files, creating or updating the POT file for a given locale directory.
Parameters
| Name | Type | Description |
|---|---|---|
| locale_dir | string | The target directory where the resulting POT file will be stored. |
| files | list | The collection of translatable files belonging to this specific locale directory. |
write_po_file()
@classmethod
def write_po_file(
potfile: string,
locale: string
)
Create or update the PO file for self.domain and locale. Use contents of the existing potfile.
Parameters
| Name | Type | Description |
|---|---|---|
| potfile | string | The path to the source .pot file containing the extracted messages. |
| locale | string | The language code for which the .po file is being created or updated. |
copy_plural_forms()
@classmethod
def copy_plural_forms(
msgs: string,
locale: string
) - > string
Copy plural forms header contents from a Django catalog of locale to the msgs string, inserting it at the right place. msgs should be the contents of a newly created .po file.
Parameters
| Name | Type | Description |
|---|---|---|
| msgs | string | The raw content of a .po file that needs plural form definitions. |
| locale | string | The locale code used to look up the appropriate plural forms in Django's core catalogs. |
Returns
| Type | Description |
|---|---|
string | The updated message string containing the correct plural forms header for the locale. |