A Source module is used to process different types of message sources.

There are two global variable in the module: file_sources and scanners.

The file_sources variable is used by scan_path() to determine supported file types. It is a dictionary, which contain file extensions (prefixed by dot char) in its keys and file source factories in its values. This dictionary is filled on import time using entry points from h10n.source.file group. The entry point name is used as file extension. h10n support only YAML-files out of the box, but you can add another ones using entry points.

>>> file_sources['.yaml']
<class 'h10n.source.YAMLSource'>
>>> file_sources['.yaml'] is file_sources['.yml']

The scanners variable is used by scanner() function to determine supported types of scanners. It is a dictionary, which contain protocol name of scanner in its keys, and scanners in its values. This dictionary is filled on import time using entry points from h10n.scanner group. The entry point name is used as protocol name.

>>> scanners['path']                                
<function scan_path at ...>
>>> scanners['asset']                               
<function scan_asset at ...>
>>> scanners['py']                                  
<function scan_py at ...>

A scanner is used to build locale definitions by scanning specified URIs.

The scanner accepts single argument – URI list, and returns an iterator over scanning result of each URI.

URI’s protocol is used to determine how to scan particular URI. It must be a key from the scanners dictionary from this module. For example, URI asset://myapp.resources:translations will be scanned by scan_asset().


A scanner of file system extracts locale definitions from directory path. The directory should contain subdirectories, which should be named as locale, using format xx-YY (all other will be skipped). Each subdirectory is scanned recursively. Each supported file is used for message catalog, where catalog name is equal to file name without extension relative to locale directory with slashes replaced by dots, i.e. file en-US/common/objects.yaml will be used as source for catalog common.objects in locale en-US. Supported files are detected according its extension, using registry of file sources – global variable from this module file_sources.


A scanner of Python package assets works the same way as scanner of file system. See scan_path() doc-string for details. Asset specification should be in format package.name:asset/path, where asset/path is a path, relative to package.name package path.


A scanner of Python modules extracts locale definitions from source code directly. Accepts spec argument, which should be a string in format modlule.name:locale_definitions. If definition part is empty, i.e. spec is passed as module.name, name locales is used by default. So, module.name is equal to module.name:locales.

class h10n.source.YAMLSource(path)

A message source, which extracts message definitions from YAML-files

Project Versions

Previous topic


Next topic


This Page