storage¶

Classes that represent various storage formats for localization.

base¶

Base classes for storage interfaces.

class translate.storage.base.DictStore(unitclass=None, encoding=None)¶

Extensions = None¶: A list of file extentions associated with this store type

Mimetypes = None¶: A list of MIME types associated with this store type

Name = 'Base translation store'¶: The human usable name of this store type

UnitClass¶: alias of TranslationUnit

add_unit_to_index(unit)¶: Add a unit to source and location idexes.

addsourceunit(source)¶

Add and returns a new unit with the given source string.

Return type:: TranslationUnit

addunit(unit)¶

Append the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

detect_encoding(text: bytes, default_encodings: list[str] | None = None) → tuple[str, str]¶: Try to detect a file encoding from text, using either the chardet lib or by trying to decode the file.

static fallback_detection(text)¶: Simple detection based on BOM in case chardet is not available.

findid(id)¶: Find unit with matching id by checking id_index.

findunit(source)¶

Find the unit with the given source string.

Return type:: TranslationUnit or None

findunits(source)¶

Find the units with the given source string.

Return type:: TranslationUnit or None

getids()¶: Return a list of unit ids.

getprojectstyle()¶: Get the project type for this store.

getsourcelanguage()¶: Get the source language for this store.

gettargetlanguage()¶: Get the target language for this store.

getunits()¶: Return a list of all units in this store.

isempty()¶: Return True if the object doesn’t contain any translation units.

makeindex()¶: Indexes the items in this store. At least .sourceindex should be useful.

property merge_on¶

The matching criterion to use when merging on.

Returns:: The default matching criterion for all the subclasses.
Return type:: string

parse(data)¶: Parser to process the given source string.

classmethod parsefile(storefile)¶: Reads the given file (or opens the given filename) and parses back to an object.

classmethod parsestring(storestring)¶: Convert the string representation back to an object.

remove_unit_from_index(unit)¶: Remove a unit from source and locaton indexes.

removeunit(unit)¶

Remove the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

require_index()¶: Make sure source index exists.

save()¶: Save to the file that data was originally read from, if available.

savefile(storefile)¶: Write the string representation to the given file (or filename).

serialize(out)¶: Converts to a bytes representation that can be parsed back using parsestring(). out should be an open file-like objects to write to.

setprojectstyle(project_style)¶: Set the project type for this store.

setsourcelanguage(sourcelanguage)¶: Set the source language for this store.

settargetlanguage(targetlanguage)¶: Set the target language for this store.

suggestions_in_format = False¶: Indicates if format can store suggestions and alternative translation for a unit

translate(source)¶

Return the translated string for a given source string.

Return type:: String or None

unit_iter()¶: Iterator over all the units in this store.

class translate.storage.base.DictUnit(source=None)¶

adderror(errorname, errortext)¶

Adds an error message to this unit.

Parameters:

errorname (string) – A single word to id the error.
errortext (string) – The text describing the error.

addlocation(location)¶: Add one location to the list of locations.

Note

Shouldn’t be implemented if the format doesn’t support it.

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶

Adds a note (comment).

Parameters:

text (string) – Usually just a sentence or two.
origin (string) – Specifies who/where the comment comes from. Origin can be one of the following text strings: - ‘translator’ - ‘developer’, ‘programmer’, ‘source code’ (synonyms)

classmethod buildfromunit(unit)¶

Build a native unit from a foreign unit.

Preserving as much information as possible.

static getcontext()¶: Get the message context.

static geterrors()¶

Get all error messages.

Return type:: Dictionary

getid()¶

A unique identifier for this unit.

Return type:: string
Returns:: an identifier for this unit that is unique in the store

Derived classes should override this in a way that guarantees a unique identifier for each unit in the store.

static getlocations()¶

A list of source code locations.

Return type:: List

Note

Shouldn’t be implemented if the format doesn’t support it.

getnotes(origin=None)¶

Returns all notes about this unit.

It will probably be freeform text or something reasonable that can be synthesised by the format. It should not include location comments (see getlocations()).

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

getvalue()¶: Returns dictionary for serialization.

static hasplural()¶: Tells whether or not this specific unit has plural strings.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Used to see if this unit has no source or target string.

Note

This is probably used more to find translatable units, and we might want to move in that direction rather and get rid of this.

static isfuzzy()¶: Indicates whether this unit is fuzzy.

static isheader()¶: Indicates whether this unit is a header.

static isobsolete()¶: Indicate whether a unit is obsolete.

static isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Make a unit obsolete.

markfuzzy(value=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶

Marks the unit to indicate whether it needs review.

Parameters:

needsreview – Defaults to True.
explanation – Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

merge(otherunit, overwrite=False, comments=True, authoritative=False)¶: Do basic format agnostic merging.

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

removenotes(origin=None)¶: Remove all the translator’s notes.

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(context)¶: Set the message context.

setid(value, unitid=None)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

unit_iter()¶: Iterator that only returns this unit.

exception translate.storage.base.ParseError(inner_exc)¶

add_note()¶: Exception.add_note(note) – add a note to the exception

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class translate.storage.base.TranslationStore(unitclass=None, encoding=None)¶

Base class for stores for multiple translation units of type UnitClass.

Extensions = None¶: A list of file extentions associated with this store type

Mimetypes = None¶: A list of MIME types associated with this store type

Name = 'Base translation store'¶: The human usable name of this store type

UnitClass¶

The class of units that will be instantiated and used by this class

alias of TranslationUnit

add_unit_to_index(unit)¶: Add a unit to source and location idexes.

addsourceunit(source)¶

Add and returns a new unit with the given source string.

Return type:: TranslationUnit

addunit(unit)¶

Append the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

detect_encoding(text: bytes, default_encodings: list[str] | None = None) → tuple[str, str]¶: Try to detect a file encoding from text, using either the chardet lib or by trying to decode the file.

static fallback_detection(text)¶: Simple detection based on BOM in case chardet is not available.

findid(id)¶: Find unit with matching id by checking id_index.

findunit(source)¶

Find the unit with the given source string.

Return type:: TranslationUnit or None

findunits(source)¶

Find the units with the given source string.

Return type:: TranslationUnit or None

getids()¶: Return a list of unit ids.

getprojectstyle()¶: Get the project type for this store.

getsourcelanguage()¶: Get the source language for this store.

gettargetlanguage()¶: Get the target language for this store.

getunits()¶: Return a list of all units in this store.

isempty()¶: Return True if the object doesn’t contain any translation units.

makeindex()¶: Indexes the items in this store. At least .sourceindex should be useful.

property merge_on¶

The matching criterion to use when merging on.

Returns:: The default matching criterion for all the subclasses.
Return type:: string

parse(data)¶: Parser to process the given source string.

classmethod parsefile(storefile)¶: Reads the given file (or opens the given filename) and parses back to an object.

classmethod parsestring(storestring)¶: Convert the string representation back to an object.

remove_unit_from_index(unit)¶: Remove a unit from source and locaton indexes.

removeunit(unit)¶

Remove the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

require_index()¶: Make sure source index exists.

save()¶: Save to the file that data was originally read from, if available.

savefile(storefile)¶: Write the string representation to the given file (or filename).

serialize(out)¶: Converts to a bytes representation that can be parsed back using parsestring(). out should be an open file-like objects to write to.

setprojectstyle(project_style)¶: Set the project type for this store.

setsourcelanguage(sourcelanguage)¶: Set the source language for this store.

settargetlanguage(targetlanguage)¶: Set the target language for this store.

suggestions_in_format = False¶: Indicates if format can store suggestions and alternative translation for a unit

translate(source)¶

Return the translated string for a given source string.

Return type:: String or None

unit_iter()¶: Iterator over all the units in this store.

class translate.storage.base.TranslationUnit(source=None)¶

Base class for translation units.

Our concept of a translation unit is influenced heavily by XLIFF.

As such most of the method- and variable names borrows from XLIFF terminology.

A translation unit consists of the following:

A source string. This is the original translatable text.
A target string. This is the translation of the source.
Zero or more notes on the unit. Notes would typically be some comments from a translator on the unit, or some comments originating from the source code.
Zero or more locations. Locations indicate where in the original source code this unit came from.
Zero or more errors. Some tools (eg. pofilter) can run checks on translations and produce error messages.

adderror(errorname, errortext)¶

Adds an error message to this unit.

Parameters:

errorname (string) – A single word to id the error.
errortext (string) – The text describing the error.

addlocation(location)¶: Add one location to the list of locations.

Note

Shouldn’t be implemented if the format doesn’t support it.

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶

Adds a note (comment).

Parameters:

text (string) – Usually just a sentence or two.
origin (string) – Specifies who/where the comment comes from. Origin can be one of the following text strings: - ‘translator’ - ‘developer’, ‘programmer’, ‘source code’ (synonyms)

classmethod buildfromunit(unit)¶

Build a native unit from a foreign unit.

Preserving as much information as possible.

static getcontext()¶: Get the message context.

static geterrors()¶

Get all error messages.

Return type:: Dictionary

getid()¶

A unique identifier for this unit.

Return type:: string
Returns:: an identifier for this unit that is unique in the store

Derived classes should override this in a way that guarantees a unique identifier for each unit in the store.

static getlocations()¶

A list of source code locations.

Return type:: List

Note

Shouldn’t be implemented if the format doesn’t support it.

getnotes(origin=None)¶

Returns all notes about this unit.

It will probably be freeform text or something reasonable that can be synthesised by the format. It should not include location comments (see getlocations()).

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

static hasplural()¶: Tells whether or not this specific unit has plural strings.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Used to see if this unit has no source or target string.

Note

This is probably used more to find translatable units, and we might want to move in that direction rather and get rid of this.

static isfuzzy()¶: Indicates whether this unit is fuzzy.

static isheader()¶: Indicates whether this unit is a header.

static isobsolete()¶: Indicate whether a unit is obsolete.

static isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Make a unit obsolete.

markfuzzy(value=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶

Marks the unit to indicate whether it needs review.

Parameters:

needsreview – Defaults to True.
explanation – Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

merge(otherunit, overwrite=False, comments=True, authoritative=False)¶: Do basic format agnostic merging.

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

removenotes(origin=None)¶: Remove all the translator’s notes.

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(context)¶: Set the message context.

setid(value)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

unit_iter()¶: Iterator that only returns this unit.

benchmark¶

class translate.storage.benchmark.TranslateBenchmarker(test_dir, storeclass)¶

class to aid in benchmarking Translate Toolkit stores.

clear_test_dir()¶: Removes the given directory.

create_sample_files(num_dirs, files_per_dir, strings_per_file, source_words_per_string, target_words_per_string)¶: Creates sample files for benchmarking.

parse_files(file_dir=None)¶: Parses all the files in the test directory into memory.

parse_placeables()¶: Parses placeables.

bundleprojstore¶

class translate.storage.bundleprojstore.BundleProjectStore(fname)¶

Represents a translate project bundle (zip archive).

append_file(afile, fname, ftype='trans', delete_orig=False)¶

Append the given file to the project with the given filename, marked to be of type ftype (‘src’, ‘trans’, ‘tgt’).

Parameters:: delete_orig – If True, as set by convert_forward(), afile is deleted after appending, if possible.

Note

For this implementation, the appended file will be deleted from disk if delete_orig is True.

cleanup()¶: Clean up our mess: remove temporary files.

get_file(fname)¶: Retrieve a project file (source, translation or target file) from the project archive.

get_filename_type(fname)¶: Get the type of file (‘src’, ‘trans’, ‘tgt’) with the given name.

get_proj_filename(realfname)¶: Try and find a project file name for the given real file name.

load(zipname)¶: Load the bundle project from the zip file of the given name.

remove_file(fname, ftype=None)¶: Remove the file with the given project name from the project.

save(filename=None)¶: Save all project files to the bundle zip file.

property sourcefiles¶: Read-only access to self._sourcefiles.

property targetfiles¶: Read-only access to self._targetfiles.

property transfiles¶: Read-only access to self._transfiles.

update_file(pfname, infile)¶

Updates the file with the given project file name with the contents of infile.

Returns:: the results from BundleProjStore.append_file().

exception translate.storage.bundleprojstore.InvalidBundleError¶

add_note()¶: Exception.add_note(note) – add a note to the exception

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

catkeys¶

Manage the Haiku catkeys translation format.

The Haiku catkeys format is the translation format used for localisation of the Haiku operating system.

It is a bilingual base class derived format with CatkeysFile and CatkeysUnit providing file and unit level access. The file format is described here: http://www.haiku-os.org/blog/pulkomandy/2009-09-24_haiku_locale_kit_translator_handbook

Implementation

The implementation covers the full requirements of a catkeys file. The files are simple Tab Separated Value (TSV) files that can be read by Microsoft Excel and other spreadsheet programs. They use the .txt extension which does make it more difficult to automatically identify such files.

The dialect of the TSV files is specified by CatkeysDialect.

Encoding

The files are UTF-8 encoded.

Header

CatkeysHeader provides header management support.

Escaping

catkeys seem to escape things like in C++ (strings are just extracted from the source code unchanged, it seems.

Functions allow for _escape() and _unescape().

class translate.storage.catkeys.CatkeysDialect¶: Describe the properties of a catkeys generated TAB-delimited file.

class translate.storage.catkeys.CatkeysFile(inputfile=None, **kwargs)¶

A catkeys translation memory file.

Extensions = ['catkeys']¶: A list of file extentions associated with this store type

Mimetypes = ['application/x-catkeys']¶: A list of MIME types associated with this store type

Name = 'Haiku catkeys file'¶: The human usable name of this store type

UnitClass¶: alias of CatkeysUnit

add_unit_to_index(unit)¶: Add a unit to source and location idexes.

addsourceunit(source)¶

Add and returns a new unit with the given source string.

Return type:: TranslationUnit

addunit(unit)¶

Append the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

detect_encoding(text: bytes, default_encodings: list[str] | None = None) → tuple[str, str]¶: Try to detect a file encoding from text, using either the chardet lib or by trying to decode the file.

static fallback_detection(text)¶: Simple detection based on BOM in case chardet is not available.

findid(id)¶: Find unit with matching id by checking id_index.

findunit(source)¶

Find the unit with the given source string.

Return type:: TranslationUnit or None

findunits(source)¶

Find the units with the given source string.

Return type:: TranslationUnit or None

getids()¶: Return a list of unit ids.

getprojectstyle()¶: Get the project type for this store.

getsourcelanguage()¶: Get the source language for this store.

gettargetlanguage()¶: Get the target language for this store.

getunits()¶: Return a list of all units in this store.

isempty()¶: Return True if the object doesn’t contain any translation units.

makeindex()¶: Indexes the items in this store. At least .sourceindex should be useful.

property merge_on¶

The matching criterion to use when merging on.

Returns:: The default matching criterion for all the subclasses.
Return type:: string

parse(input)¶: Parse the given file or file source string.

classmethod parsefile(storefile)¶: Reads the given file (or opens the given filename) and parses back to an object.

classmethod parsestring(storestring)¶: Convert the string representation back to an object.

remove_unit_from_index(unit)¶: Remove a unit from source and locaton indexes.

removeunit(unit)¶

Remove the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

require_index()¶: Make sure source index exists.

save()¶: Save to the file that data was originally read from, if available.

savefile(storefile)¶: Write the string representation to the given file (or filename).

serialize(out)¶: Converts to a bytes representation that can be parsed back using parsestring(). out should be an open file-like objects to write to.

setprojectstyle(project_style)¶: Set the project type for this store.

setsourcelanguage(sourcelanguage)¶: Set the source language for this store.

settargetlanguage(newlang)¶: Set the target language for this store.

suggestions_in_format = False¶: Indicates if format can store suggestions and alternative translation for a unit

translate(source)¶

Return the translated string for a given source string.

Return type:: String or None

unit_iter()¶: Iterator over all the units in this store.

class translate.storage.catkeys.CatkeysHeader(header=None)¶

A catkeys translation memory header.

setchecksum(checksum)¶: Set the checksum for the file.

settargetlanguage(newlang)¶: Set a human readable target language.

class translate.storage.catkeys.CatkeysUnit(source=None)¶

A catkeys translation memory unit.

adderror(errorname, errortext)¶

Adds an error message to this unit.

Parameters:

errorname (string) – A single word to id the error.
errortext (string) – The text describing the error.

addlocation(location)¶: Add one location to the list of locations.

Note

Shouldn’t be implemented if the format doesn’t support it.

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶

Adds a note (comment).

Parameters:

text (string) – Usually just a sentence or two.
origin (string) – Specifies who/where the comment comes from. Origin can be one of the following text strings: - ‘translator’ - ‘developer’, ‘programmer’, ‘source code’ (synonyms)

classmethod buildfromunit(unit)¶

Build a native unit from a foreign unit.

Preserving as much information as possible.

property dict¶: Get the dictionary of values for a catkeys line.

getcontext()¶: Get the message context.

getdict()¶: Get the dictionary of values for a catkeys line.

static geterrors()¶

Get all error messages.

Return type:: Dictionary

getid()¶

A unique identifier for this unit.

Return type:: string
Returns:: an identifier for this unit that is unique in the store

Derived classes should override this in a way that guarantees a unique identifier for each unit in the store.

static getlocations()¶

A list of source code locations.

Return type:: List

Note

Shouldn’t be implemented if the format doesn’t support it.

getnotes(origin=None)¶

Returns all notes about this unit.

It will probably be freeform text or something reasonable that can be synthesised by the format. It should not include location comments (see getlocations()).

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

static hasplural()¶: Tells whether or not this specific unit has plural strings.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Used to see if this unit has no source or target string.

Note

This is probably used more to find translatable units, and we might want to move in that direction rather and get rid of this.

static isfuzzy()¶: Indicates whether this unit is fuzzy.

static isheader()¶: Indicates whether this unit is a header.

static isobsolete()¶: Indicate whether a unit is obsolete.

static isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Make a unit obsolete.

markfuzzy(present=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶

Marks the unit to indicate whether it needs review.

Parameters:

needsreview – Defaults to True.
explanation – Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

merge(otherunit, overwrite=False, comments=True, authoritative=False)¶: Do basic format agnostic merging.

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

removenotes(origin=None)¶: Remove all the translator’s notes.

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(context)¶: Set the message context.

setdict(newdict)¶

Set the dictionary of values for a catkeys line.

Parameters:: newdict (Dict) – a new dictionary with catkeys line elements

setid(value)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

unit_iter()¶: Iterator that only returns this unit.

translate.storage.catkeys.FIELDNAMES = ['source', 'context', 'comment', 'target']¶: Field names for a catkeys TU

translate.storage.catkeys.FIELDNAMES_HEADER = ['version', 'language', 'mimetype', 'checksum']¶: Field names for the catkeys header

translate.storage.catkeys.FIELDNAMES_HEADER_DEFAULTS = {'checksum': '', 'language': '', 'mimetype': '', 'version': '1'}¶: Default or minimum header entries for a catkeys file

cpo¶

Classes that hold units of .po files (pounit) or entire files (pofile).

Gettext-style .po (or .pot) files are used in translations for KDE, GNOME and many other projects.

This uses libgettextpo from the gettext package. Any version before 0.17 will at least cause some subtle bugs or may not work at all. Developers might want to have a look at gettext-tools/libgettextpo/gettext-po.h from the gettext package for the public API of the library.

translate.storage.cpo.get_libgettextpo_version()¶

Returns the libgettextpo version.

Return type:: three-value tuple
Returns:: libgettextpo version in the following format:: (major version, minor version, subminor version)

translate.storage.cpo.lsep = ' '¶: Separator for #: entries

class translate.storage.cpo.po_error_handler¶

class translate.storage.cpo.po_file¶

translate.storage.cpo.po_file_t¶: A po_file_t represents a PO file.

class translate.storage.cpo.po_filepos¶

translate.storage.cpo.po_filepos_t¶: A po_filepos_t represents the position in a PO file.

class translate.storage.cpo.po_iterator¶

translate.storage.cpo.po_iterator_t¶: A po_iterator_t represents an iterator through a PO file.

class translate.storage.cpo.po_message¶

translate.storage.cpo.po_message_t¶: A po_message_t represents a message in a PO file.

class translate.storage.cpo.po_xerror_handler¶

class translate.storage.cpo.pofile(inputfile=None, noheader=False, **kwargs)¶

Extensions = ['po', 'pot']¶: A list of file extentions associated with this store type

Mimetypes = ['text/x-gettext-catalog', 'text/x-gettext-translation', 'text/x-po', 'text/x-pot']¶: A list of MIME types associated with this store type

Name = 'Gettext PO file'¶: The human usable name of this store type

UnitClass¶: alias of pounit

add_unit_to_index(unit)¶: Add a unit to source and location idexes.

addsourceunit(source)¶

Add and returns a new unit with the given source string.

Return type:: TranslationUnit

addunit(unit, new=True)¶

Append the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

detect_encoding(text: bytes, default_encodings: list[str] | None = None) → tuple[str, str]¶: Try to detect a file encoding from text, using either the chardet lib or by trying to decode the file.

static fallback_detection(text)¶: Simple detection based on BOM in case chardet is not available.

findid(id)¶: Find unit with matching id by checking id_index.

findunit(source)¶

Find the unit with the given source string.

Return type:: TranslationUnit or None

findunits(source)¶

Find the units with the given source string.

Return type:: TranslationUnit or None

getheaderplural()¶: Returns the nplural and plural values from the header.

getids()¶: Return a list of unit ids.

getprojectstyle()¶

Return the project based on information in the header.

The project is determined in the following sequence:

Use the ‘X-Project-Style’ entry in the header.
Use ‘Report-Msgid-Bug-To’ entry
Use the ‘X-Accelerator’ entry
Use the Project ID
Analyse the file itself (not yet implemented)

getsourcelanguage()¶: Get the source language for this store.

gettargetlanguage()¶

Return the target language based on information in the header.

The target language is determined in the following sequence:

Use the ‘Language’ entry in the header.
Poedit’s custom headers.
Analysing the ‘Language-Team’ entry.

getunits()¶: Return a list of all units in this store.

header()¶: Returns the header element, or None. Only the first element is allowed to be a header. Note that this could still return an empty header element, if present.

init_headers(charset='UTF-8', encoding='8bit', **kwargs)¶: Sets default values for po headers.

isempty()¶: Returns True if the object doesn’t contain any translation units.

makeheader(**kwargs)¶

Create a header for the given filename.

Check .makeheaderdict() for information on parameters.

makeheaderdict(charset='CHARSET', encoding='ENCODING', project_id_version=None, pot_creation_date=None, po_revision_date=None, last_translator=None, language_team=None, mime_version=None, plural_forms=None, report_msgid_bugs_to=None, **kwargs)¶

Create a header dictionary with useful defaults.

pot_creation_date can be None (current date) or a value (datetime or string) po_revision_date can be None (form), False (=pot_creation_date), True (=now), or a value (datetime or string)

Returns:: Dictionary with the header items
Return type:: dict of strings

makeindex()¶: Indexes the items in this store. At least .sourceindex should be useful.

property merge_on¶: The matching criterion to use when merging on.

mergeheaders(otherstore)¶

Merges another header with this header.

This header is assumed to be the template.

parse(input)¶: Parser to process the given source string.

classmethod parsefile(storefile)¶: Reads the given file (or opens the given filename) and parses back to an object.

parseheader()¶: Parses the PO header and returns the interpreted values as a dictionary.

classmethod parsestring(storestring)¶: Convert the string representation back to an object.

remove_unit_from_index(unit)¶: Remove a unit from source and locaton indexes.

removeduplicates(duplicatestyle='merge')¶: Make sure each msgid is unique ; merge comments etc from duplicates into original.

removeunit(unit)¶

Remove the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

require_index()¶: Make sure source index exists.

save()¶: Save to the file that data was originally read from, if available.

savefile(storefile)¶: Write the string representation to the given file (or filename).

serialize(out)¶: Converts to a bytes representation that can be parsed back using parsestring(). out should be an open file-like objects to write to.

setprojectstyle(project_style)¶

Set the project in the header.

Parameters:: project_style (str) – the new project

setsourcelanguage(sourcelanguage)¶: Set the source language for this store.

settargetlanguage(lang)¶

Set the target language in the header.

This removes any custom Poedit headers if they exist.

Parameters:: lang (str) – the new target language code

suggestions_in_format = False¶: Indicates if format can store suggestions and alternative translation for a unit

translate(source)¶

Return the translated string for a given source string.

Return type:: String or None

unit_iter()¶: Iterator over all the units in this store.

updatecontributor(name, email=None)¶: Add contribution comments if necessary.

updateheader(add=False, **kwargs)¶

Updates the fields in the PO style header.

This will create a header if add == True.

updateheaderplural(nplurals, plural)¶: Update the Plural-Form PO header.

class translate.storage.cpo.pounit(source=None, encoding='utf-8', gpo_message=None)¶

CPO_ENC = 'utf-8'¶: fixed encoding that is always used for cPO structure (self._gpo_message)

adderror(errorname, errortext)¶: Adds an error message to this unit.

addlocation(location)¶: Add one location to the list of locations.

Note

Shouldn’t be implemented if the format doesn’t support it.

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶

Adds a note (comment).

Parameters:

text (string) – Usually just a sentence or two.
origin (string) – Specifies who/where the comment comes from. Origin can be one of the following text strings: - ‘translator’ - ‘developer’, ‘programmer’, ‘source code’ (synonyms)

classmethod buildfromunit(unit, encoding=None)¶: Build a native unit from a foreign unit, preserving as much information as possible.

getcontext()¶: Get the message context.

geterrors()¶: Get all error messages.

getid()¶: The unique identifier for this unit according to the conventions in .mo files.

getlocations()¶

A list of source code locations.

Return type:: List

Note

Shouldn’t be implemented if the format doesn’t support it.

getnotes(origin=None)¶

Returns all notes about this unit.

It will probably be freeform text or something reasonable that can be synthesised by the format. It should not include location comments (see getlocations()).

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

hasplural()¶: Tells whether or not this specific unit has plural strings.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Used to see if this unit has no source or target string.

Note

This is probably used more to find translatable units, and we might want to move in that direction rather and get rid of this.

isfuzzy()¶: Indicates whether this unit is fuzzy.

isheader()¶: Indicates whether this unit is a header.

isobsolete()¶: Indicate whether a unit is obsolete.

isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Make a unit obsolete.

markfuzzy(present=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶: Marks the unit to indicate whether it needs review. Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

merge(otherpo, overwrite=False, comments=True, authoritative=False)¶

Merges the otherpo (with the same msgid) into this one.

Overwrite non-blank self.msgstr only if overwrite is True merge comments only if comments is True

property msgidcomment¶

Extract KDE style msgid comments from the unit.

Return type:: String
Returns:: Returns the extracted msgidcomments found in this unit’s msgid.

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

removenotes(origin=None)¶: Remove all the translator’s notes.

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(context)¶: Set the message context.

setid(value)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

unit_iter()¶: Iterator that only returns this unit.

csvl10n¶

classes that hold units of comma-separated values (.csv) files (csvunit) or entire files (csvfile) for use with localisation.

class translate.storage.csvl10n.DefaultDialect¶

class translate.storage.csvl10n.csvfile(inputfile=None, fieldnames=None, encoding='auto')¶

This class represents a .csv file with various lines. The default format contains three columns: location, source, target.

Extensions = ['csv']¶: A list of file extentions associated with this store type

Mimetypes = ['text/comma-separated-values', 'text/csv']¶: A list of MIME types associated with this store type

Name = 'Comma Separated Value'¶: The human usable name of this store type

UnitClass¶: alias of csvunit

add_unit_to_index(unit)¶: Add a unit to source and location idexes.

addsourceunit(source)¶

Add and returns a new unit with the given source string.

Return type:: TranslationUnit

addunit(unit)¶

Append the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

detect_encoding(text: bytes, default_encodings: list[str] | None = None) → tuple[str, str]¶: Try to detect a file encoding from text, using either the chardet lib or by trying to decode the file.

static fallback_detection(text)¶: Simple detection based on BOM in case chardet is not available.

findid(id)¶: Find unit with matching id by checking id_index.

findunit(source)¶

Find the unit with the given source string.

Return type:: TranslationUnit or None

findunits(source)¶

Find the units with the given source string.

Return type:: TranslationUnit or None

getids()¶: Return a list of unit ids.

getprojectstyle()¶: Get the project type for this store.

getsourcelanguage()¶: Get the source language for this store.

gettargetlanguage()¶: Get the target language for this store.

getunits()¶: Return a list of all units in this store.

isempty()¶: Return True if the object doesn’t contain any translation units.

makeindex()¶: Indexes the items in this store. At least .sourceindex should be useful.

property merge_on¶

The matching criterion to use when merging on.

Returns:: The default matching criterion for all the subclasses.
Return type:: string

parse(csvsrc, sample_length: int | None = 1024, *, dialect: None | str = None)¶: Parser to process the given source string.

classmethod parsefile(storefile)¶: Reads the given file (or opens the given filename) and parses back to an object.

classmethod parsestring(storestring)¶: Convert the string representation back to an object.

remove_unit_from_index(unit)¶: Remove a unit from source and locaton indexes.

removeunit(unit)¶

Remove the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

require_index()¶: Make sure source index exists.

save()¶: Save to the file that data was originally read from, if available.

savefile(storefile)¶: Write the string representation to the given file (or filename).

serialize(out)¶: Write to file.

setprojectstyle(project_style)¶: Set the project type for this store.

setsourcelanguage(sourcelanguage)¶: Set the source language for this store.

settargetlanguage(targetlanguage)¶: Set the target language for this store.

suggestions_in_format = False¶: Indicates if format can store suggestions and alternative translation for a unit

translate(source)¶

Return the translated string for a given source string.

Return type:: String or None

unit_iter()¶: Iterator over all the units in this store.

class translate.storage.csvl10n.csvunit(source=None)¶

add_spreadsheet_escapes(source, target)¶: Add common spreadsheet escapes to two strings.

adderror(errorname, errortext)¶

Adds an error message to this unit.

Parameters:

errorname (string) – A single word to id the error.
errortext (string) – The text describing the error.

addlocation(location)¶: Add one location to the list of locations.

Note

Shouldn’t be implemented if the format doesn’t support it.

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶

Adds a note (comment).

Parameters:

text (string) – Usually just a sentence or two.
origin (string) – Specifies who/where the comment comes from. Origin can be one of the following text strings: - ‘translator’ - ‘developer’, ‘programmer’, ‘source code’ (synonyms)

classmethod buildfromunit(unit)¶

Build a native unit from a foreign unit.

Preserving as much information as possible.

getcontext()¶: Get the message context.

static geterrors()¶

Get all error messages.

Return type:: Dictionary

getid()¶

A unique identifier for this unit.

Return type:: string
Returns:: an identifier for this unit that is unique in the store

Derived classes should override this in a way that guarantees a unique identifier for each unit in the store.

getlocations()¶

A list of source code locations.

Return type:: List

Note

Shouldn’t be implemented if the format doesn’t support it.

getnotes(origin=None)¶

Returns all notes about this unit.

It will probably be freeform text or something reasonable that can be synthesised by the format. It should not include location comments (see getlocations()).

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

static hasplural()¶: Tells whether or not this specific unit has plural strings.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Used to see if this unit has no source or target string.

Note

This is probably used more to find translatable units, and we might want to move in that direction rather and get rid of this.

isfuzzy()¶: Indicates whether this unit is fuzzy.

static isheader()¶: Indicates whether this unit is a header.

static isobsolete()¶: Indicate whether a unit is obsolete.

static isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Make a unit obsolete.

markfuzzy(value=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶

Marks the unit to indicate whether it needs review.

Parameters:

needsreview – Defaults to True.
explanation – Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

match_header()¶: See if unit might be a header.

merge(otherunit, overwrite=False, comments=True, authoritative=False)¶: Do basic format agnostic merging.

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

remove_spreadsheet_escapes(source, target)¶: Remove common spreadsheet escapes from two strings.

removenotes(origin=None)¶: Remove all the translator’s notes.

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(value)¶: Set the message context.

setid(value)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

unit_iter()¶: Iterator that only returns this unit.

translate.storage.csvl10n.detect_header(inputfile, dialect, fieldnames)¶: Test if file has a header or not, also returns number of columns in first row.

translate.storage.csvl10n.valid_fieldnames(fieldnames)¶: Check if fieldnames are valid, that is at least one field is identified as the source.

directory¶

This module provides functionality to work with directories.

class translate.storage.directory.Directory(dir=None)¶

This class represents a directory.

file_iter()¶: Iterator over (dir, filename) for all files in this directory.

getfiles()¶: Returns a list of (dir, filename) tuples for all the file names in this directory.

getunits()¶: List of all the units in all the files in this directory.

scanfiles()¶: Populate the internal file data.

unit_iter()¶: Iterator over all the units in all the files in this directory.

dtd¶

Classes that hold units of .dtd files (dtdunit) or entire files (dtdfile).

These are specific .dtd files for localisation used by mozilla.

Specifications

The following information is provided by Mozilla:

Specification

There is a grammar for entity definitions, which isn’t really precise, as the spec says. There’s no formal specification for DTD files, it’s just “whatever makes this work” basically. The whole piece is clearly not the strongest point of the xml spec

XML elements are allowed in entity values. A number of things that are allowed will just break the resulting document, Mozilla forbids these in their DTD parser.

Dialects

There are two dialects:

Regular DTD
Android DTD

Both dialects are similar, but the Android DTD uses some particular escapes that regular DTDs don’t have.

Escaping in regular DTD

In DTD usually there are characters escaped in the entities. In order to ease the translation some of those escaped characters are unescaped when reading from, or converting, the DTD, and that are escaped again when saving, or converting to a DTD.

In regular DTD the following characters are usually or sometimes escaped:

The % character is escaped using % or % or %
The “ character is escaped using "
The ‘ character is escaped using ' (partial roundtrip)
The & character is escaped using &
The < character is escaped using < (not yet implemented)
The > character is escaped using > (not yet implemented)

Besides the previous ones there are a lot of escapes for a huge number of characters. This escapes usually have the form of &#NUMBER; where NUMBER represents the numerical code for the character.

There are a few particularities in DTD escaping. Some of the escapes are not yet implemented since they are not really necessary, or because its implementation is too hard.

A special case is the ‘ escaping using ' which doesn’t provide a full roundtrip conversion in order to support some special Mozilla DTD files.

Also the “ character is never escaped in the case that the previous character is = (the sequence =” is present on the string) in order to avoid escaping the “ character indicating an attribute assignment, for example in a href attribute for an a tag in HTML (anchor tag).

Escaping in Android DTD

It has the sames escapes as in regular DTD, plus this ones:

The ‘ character is escaped using ' or ' or u0027
The “ character is escaped using "

translate.storage.dtd.accesskeysuffixes = ('.accesskey', '.accessKey', '.akey')¶: Accesskey Suffixes: entries with this suffix may be combined with labels ending in labelsuffixes into accelerator notation

class translate.storage.dtd.dtdfile(inputfile=None, android=False)¶

A .dtd file made up of dtdunits.

Extensions = None¶: A list of file extentions associated with this store type

Mimetypes = None¶: A list of MIME types associated with this store type

Name = 'Base translation store'¶: The human usable name of this store type

UnitClass¶: alias of dtdunit

add_unit_to_index(unit)¶: Add a unit to source and location idexes.

addsourceunit(source)¶

Add and returns a new unit with the given source string.

Return type:: TranslationUnit

addunit(unit)¶

Append the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

detect_encoding(text: bytes, default_encodings: list[str] | None = None) → tuple[str, str]¶: Try to detect a file encoding from text, using either the chardet lib or by trying to decode the file.

static fallback_detection(text)¶: Simple detection based on BOM in case chardet is not available.

findid(id)¶: Find unit with matching id by checking id_index.

findunit(source)¶

Find the unit with the given source string.

Return type:: TranslationUnit or None

findunits(source)¶

Find the units with the given source string.

Return type:: TranslationUnit or None

getids()¶: Return a list of unit ids.

getprojectstyle()¶: Get the project type for this store.

getsourcelanguage()¶: Get the source language for this store.

gettargetlanguage()¶: Get the target language for this store.

getunits()¶: Return a list of all units in this store.

isempty()¶: Return True if the object doesn’t contain any translation units.

makeindex()¶: Indexes the items in this store. At least .sourceindex should be useful.

property merge_on¶

The matching criterion to use when merging on.

Returns:: The default matching criterion for all the subclasses.
Return type:: string

parse(dtdsrc)¶: Read the source code of a dtd file in and include them as dtdunits in self.units.

classmethod parsefile(storefile)¶: Reads the given file (or opens the given filename) and parses back to an object.

classmethod parsestring(storestring)¶: Convert the string representation back to an object.

remove_unit_from_index(unit)¶: Remove a unit from source and locaton indexes.

removeunit(unit)¶

Remove the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

require_index()¶: Make sure source index exists.

save()¶: Save to the file that data was originally read from, if available.

savefile(storefile)¶: Write the string representation to the given file (or filename).

serialize(out)¶: Write content to file.

setprojectstyle(project_style)¶: Set the project type for this store.

setsourcelanguage(sourcelanguage)¶: Set the source language for this store.

settargetlanguage(targetlanguage)¶: Set the target language for this store.

suggestions_in_format = False¶: Indicates if format can store suggestions and alternative translation for a unit

translate(source)¶

Return the translated string for a given source string.

Return type:: String or None

unit_iter()¶: Iterator over all the units in this store.

class translate.storage.dtd.dtdunit(source='', android=False)¶

An entity definition from a DTD file (and any associated comments).

adderror(errorname, errortext)¶

Adds an error message to this unit.

Parameters:

errorname (string) – A single word to id the error.
errortext (string) – The text describing the error.

addlocation(location)¶: Set the entity to the given “location”.

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶

Adds a note (comment).

Parameters:

text (string) – Usually just a sentence or two.
origin (string) – Specifies who/where the comment comes from. Origin can be one of the following text strings: - ‘translator’ - ‘developer’, ‘programmer’, ‘source code’ (synonyms)

classmethod buildfromunit(unit)¶

Build a native unit from a foreign unit.

Preserving as much information as possible.

static getcontext()¶: Get the message context.

static geterrors()¶

Get all error messages.

Return type:: Dictionary

getid()¶

A unique identifier for this unit.

Return type:: string
Returns:: an identifier for this unit that is unique in the store

Derived classes should override this in a way that guarantees a unique identifier for each unit in the store.

getlocations()¶: Return the entity as location (identifier).

getnotes(origin=None)¶

Returns all notes about this unit.

It will probably be freeform text or something reasonable that can be synthesised by the format. It should not include location comments (see getlocations()).

getoutput()¶: Convert the dtd entity back to string form.

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

static hasplural()¶: Tells whether or not this specific unit has plural strings.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Returns whether this dtdunit doesn’t actually have an entity definition.

static isfuzzy()¶: Indicates whether this unit is fuzzy.

static isheader()¶: Indicates whether this unit is a header.

static isobsolete()¶: Indicate whether a unit is obsolete.

static isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Make a unit obsolete.

markfuzzy(value=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶

Marks the unit to indicate whether it needs review.

Parameters:

needsreview – Defaults to True.
explanation – Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

merge(otherunit, overwrite=False, comments=True, authoritative=False)¶: Do basic format agnostic merging.

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

parse(dtdsrc)¶: Read the first dtd element from the source code into this object, return linesprocessed.

removenotes(origin=None)¶: Remove all the translator’s notes.

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(context)¶: Set the message context.

setid(new_id)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

property source¶: Gets the unquoted source string.

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

property target¶: Gets the unquoted target string.

unit_iter()¶: Iterator that only returns this unit.

translate.storage.dtd.labelsuffixes = ('.label', '.title')¶: Label suffixes: entries with this suffix are able to be comibed with accesskeys found in in entries ending with accesskeysuffixes

translate.storage.dtd.quoteforandroid(source)¶: Escapes a line for Android DTD files.

translate.storage.dtd.quotefordtd(source)¶: Quotes and escapes a line for regular DTD files.

translate.storage.dtd.removeinvalidamps(name, value)¶

Find and remove ampersands that are not part of an entity definition.

A stray & in a DTD file can break an application’s ability to parse the file. In Mozilla localisation this is very important and these can break the parsing of files used in XUL and thus break interface rendering. Tracking down the problem is very difficult, thus by removing potential broken ampersand and warning the users we can ensure that the output DTD will always be parsable.

Parameters:

name (String) – Entity name
value (String) – Entity text value

Return type:

String

Returns:

Entity value without bad ampersands

translate.storage.dtd.unquotefromandroid(source)¶: Unquotes a quoted Android DTD definition.

translate.storage.dtd.unquotefromdtd(source)¶: Unquotes a quoted dtd definition.

_factory_classes¶

Py2exe can’t find stuff that we import dynamically, so we have this file just for the sake of the Windows installer to easily pick up all the stuff that we need and ensure they make it into the installer.

factory¶

factory methods to build real storage objects that conform to base.py.

translate.storage.factory.getclass(storefile, localfiletype=None, ignore=None, classes=None, classes_str=None, hiddenclasses=None)¶: Factory that returns the applicable class for the type of file presented. Specify ignore to ignore some part at the back of the name (like .gz).

translate.storage.factory.getobject(storefile, localfiletype=None, ignore=None, classes=None, classes_str=None, hiddenclasses=None)¶

Factory that returns a usable object for the type of file presented.

Parameters:: storefile (file or str or TranslationStore) – File object or file name.

Specify ignore to ignore some part at the back of the name (like .gz).

translate.storage.factory.supported_files()¶

Returns data about all supported files.

Returns:: list of type that include (name, extensions, mimetypes)
Return type:: list

fpo¶

Classes for the support of Gettext .po and .pot files.

This implementation assumes that cpo is working. This should not be used directly, but can be used once cpo has been established to work.

translate.storage.fpo.lsep = ' '¶: Separator for #: entries

class translate.storage.fpo.pofile(inputfile=None, noheader=False, **kwargs)¶

A .po file containing various units.

Extensions = ['po', 'pot']¶: A list of file extentions associated with this store type

Mimetypes = ['text/x-gettext-catalog', 'text/x-gettext-translation', 'text/x-po', 'text/x-pot']¶: A list of MIME types associated with this store type

Name = 'Gettext PO file'¶: The human usable name of this store type

UnitClass¶: alias of pounit

add_unit_to_index(unit)¶: Add a unit to source and location idexes.

addsourceunit(source)¶

Add and returns a new unit with the given source string.

Return type:: TranslationUnit

addunit(unit)¶

Append the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

detect_encoding(text: bytes, default_encodings: list[str] | None = None) → tuple[str, str]¶: Try to detect a file encoding from text, using either the chardet lib or by trying to decode the file.

static fallback_detection(text)¶: Simple detection based on BOM in case chardet is not available.

findid(id)¶: Find unit with matching id by checking id_index.

findunit(source)¶

Find the unit with the given source string.

Return type:: TranslationUnit or None

findunits(source)¶

Find the units with the given source string.

Return type:: TranslationUnit or None

getheaderplural()¶: Returns the nplural and plural values from the header.

getids()¶: Return a list of unit ids.

getprojectstyle()¶

Return the project based on information in the header.

The project is determined in the following sequence:

Use the ‘X-Project-Style’ entry in the header.
Use ‘Report-Msgid-Bug-To’ entry
Use the ‘X-Accelerator’ entry
Use the Project ID
Analyse the file itself (not yet implemented)

getsourcelanguage()¶: Get the source language for this store.

gettargetlanguage()¶

Return the target language based on information in the header.

The target language is determined in the following sequence:

Use the ‘Language’ entry in the header.
Poedit’s custom headers.
Analysing the ‘Language-Team’ entry.

getunits()¶: Return a list of all units in this store.

header()¶: Returns the header element, or None. Only the first element is allowed to be a header. Note that this could still return an empty header element, if present.

init_headers(charset='UTF-8', encoding='8bit', **kwargs)¶: Sets default values for po headers.

isempty()¶: Return True if the object doesn’t contain any translation units.

makeheader(**kwargs)¶

Create a header for the given filename.

Check .makeheaderdict() for information on parameters.

Create a header dictionary with useful defaults.

pot_creation_date can be None (current date) or a value (datetime or string) po_revision_date can be None (form), False (=pot_creation_date), True (=now), or a value (datetime or string)

Returns:: Dictionary with the header items
Return type:: dict of strings

makeindex()¶: Indexes the items in this store. At least .sourceindex should be useful.

property merge_on¶: The matching criterion to use when merging on.

mergeheaders(otherstore)¶

Merges another header with this header.

This header is assumed to be the template.

parse(input)¶: Parses the given file or file source string.

classmethod parsefile(storefile)¶: Reads the given file (or opens the given filename) and parses back to an object.

parseheader()¶: Parses the PO header and returns the interpreted values as a dictionary.

classmethod parsestring(storestring)¶: Convert the string representation back to an object.

remove_unit_from_index(unit)¶: Remove a unit from source and locaton indexes.

removeduplicates(duplicatestyle='merge')¶: Make sure each msgid is unique ; merge comments etc from duplicates into original.

removeunit(unit)¶

Remove the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

require_index()¶: Make sure source index exists.

save()¶: Save to the file that data was originally read from, if available.

savefile(storefile)¶: Write the string representation to the given file (or filename).

serialize(out)¶: Write content to file.

setprojectstyle(project_style)¶

Set the project in the header.

Parameters:: project_style (str) – the new project

setsourcelanguage(sourcelanguage)¶: Set the source language for this store.

settargetlanguage(lang)¶

Set the target language in the header.

This removes any custom Poedit headers if they exist.

Parameters:: lang (str) – the new target language code

suggestions_in_format = False¶: Indicates if format can store suggestions and alternative translation for a unit

translate(source)¶

Return the translated string for a given source string.

Return type:: String or None

unit_iter()¶: Iterator over all the units in this store.

updatecontributor(name, email=None)¶: Add contribution comments if necessary.

updateheader(add=False, **kwargs)¶

Updates the fields in the PO style header.

This will create a header if add == True.

updateheaderplural(nplurals, plural)¶: Update the Plural-Form PO header.

class translate.storage.fpo.pounit(source=None, **kwargs)¶

adderror(errorname, errortext)¶: Adds an error message to this unit.

addlocation(location)¶

Add a location to sourcecomments in the PO unit.

Parameters:: location (String) – Text location e.g. ‘file.c:23’ does not include #:

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶: This is modeled on the XLIFF method. See xliff.py::xliffunit.addnote.

classmethod buildfromunit(unit)¶: Build a native unit from a foreign unit, preserving as much information as possible.

getcontext()¶: Get the message context.

geterrors()¶: Get all error messages.

getid()¶: Returns a unique identifier for this unit.

getlocations()¶

Get a list of locations from sourcecomments in the PO unit.

rtype: List return: A list of the locations with ‘#: ‘ stripped

getnotes(origin=None)¶: Return comments based on origin value (programmer, developer, source code and translator).

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

hasmarkedcomment(commentmarker)¶: Check whether the given comment marker is present as # (commentmarker) …

hasplural()¶: Returns whether this pounit contains plural strings…

hastypecomment(typecomment)¶: Check whether the given type comment is present.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Used to see if this unit has no source or target string.

Note

This is probably used more to find translatable units, and we might want to move in that direction rather and get rid of this.

isfuzzy()¶: Indicates whether this unit is fuzzy.

isheader()¶: Indicates whether this unit is a header.

isobsolete()¶: Indicate whether a unit is obsolete.

isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Makes this unit obsolete.

markfuzzy(present=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶: Marks the unit to indicate whether it needs review. Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

merge(otherpo, overwrite=False, comments=True, authoritative=False)¶

Merges the otherpo (with the same msgid) into this one.

Overwrite non-blank self.msgstr only if overwrite is True merge comments only if comments is True

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

removenotes(origin=None)¶: Remove all the translator’s notes (other comments).

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(context)¶: Set the message context.

setid(value)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

settypecomment(typecomment, present=True)¶: Alters whether a given typecomment is present.

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

property target¶: Returns the unescaped msgstr.

unit_iter()¶: Iterator that only returns this unit.

html¶

module for parsing html files for translation.

class translate.storage.html.POHTMLParser(inputfile=None, callback=None)¶

EMPTY_HTML_ELEMENTS = ['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']¶: An empty element is an element that cannot have any child nodes (i.e., nested elements or text nodes). In HTML, using a closing tag on an empty element is usually invalid. Reference https://developer.mozilla.org/en-US/docs/Glossary/Empty_element

Extensions = None¶: A list of file extentions associated with this store type

Mimetypes = None¶: A list of MIME types associated with this store type

Name = 'Base translation store'¶: The human usable name of this store type

TRANSLATABLE_ATTRIBUTES = ['abbr', 'alt', 'lang', 'summary', 'title', 'value']¶: Text from these HTML attributes will be extracted as translation units. Note: the content attribute of meta tags is a special case.

TRANSLATABLE_ELEMENTS = ['address', 'article', 'aside', 'blockquote', 'caption', 'dd', 'dt', 'div', 'figcaption', 'footer', 'header', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'label', 'li', 'main', 'nav', 'option', 'p', 'pre', 'section', 'td', 'th', 'title']¶: These HTML elements (tags) will be extracted as translation units, unless they lack translatable text content. In case one translatable element is embedded in another, the outer translation unit will be split into the parts before and after the inner translation unit.

TRANSLATABLE_METADATA = ['description', 'keywords']¶: Document metadata from meta elements with these names will be extracted as translation units. Reference https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name

UnitClass¶: alias of htmlunit

add_unit_to_index(unit)¶: Add a unit to source and location idexes.

addsourceunit(source)¶

Add and returns a new unit with the given source string.

Return type:: TranslationUnit

addunit(unit)¶

Append the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

close()¶: Handle any buffered data.

detect_encoding(text: bytes, default_encodings: list[str] | None = None) → tuple[str, str]¶: Try to detect a file encoding from text, using either the chardet lib or by trying to decode the file.

do_encoding(htmlsrc)¶: Return the html text properly encoded based on a charset.

static fallback_detection(text)¶: Simple detection based on BOM in case chardet is not available.

feed(data)¶

Feed data to the parser.

Call this as often as you want, with as little or as much text as you want (may include ‘n’).

findid(id)¶: Find unit with matching id by checking id_index.

findunit(source)¶

Find the unit with the given source string.

Return type:: TranslationUnit or None

findunits(source)¶

Find the units with the given source string.

Return type:: TranslationUnit or None

get_starttag_text()¶: Return full source of start tag: ‘<…>’.

getids()¶: Return a list of unit ids.

getpos()¶: Return current line number and offset.

getprojectstyle()¶: Get the project type for this store.

getsourcelanguage()¶: Get the source language for this store.

gettargetlanguage()¶: Get the target language for this store.

getunits()¶: Return a list of all units in this store.

guess_encoding(htmlsrc)¶

Returns the encoding of the html text.

We look for ‘charset=’ within a meta tag to do this.

handle_charref(name)¶: Handle entries in the form &#NNNN; e.g. ⃡.

handle_entityref(name)¶: Handle named entities of the form &aaaa; e.g. ’.

isempty()¶: Return True if the object doesn’t contain any translation units.

makeindex()¶: Indexes the items in this store. At least .sourceindex should be useful.

property merge_on¶

The matching criterion to use when merging on.

Returns:: The default matching criterion for all the subclasses.
Return type:: string

parse(htmlsrc)¶: Parser to process the given source string.

classmethod parsefile(storefile)¶: Reads the given file (or opens the given filename) and parses back to an object.

classmethod parsestring(storestring)¶: Convert the string representation back to an object.

remove_unit_from_index(unit)¶: Remove a unit from source and locaton indexes.

removeunit(unit)¶

Remove the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

require_index()¶: Make sure source index exists.

reset()¶: Reset this instance. Loses all unprocessed data.

save()¶: Save to the file that data was originally read from, if available.

savefile(storefile)¶: Write the string representation to the given file (or filename).

serialize(out)¶: Converts to a bytes representation that can be parsed back using parsestring(). out should be an open file-like objects to write to.

setprojectstyle(project_style)¶: Set the project type for this store.

setsourcelanguage(sourcelanguage)¶: Set the source language for this store.

settargetlanguage(targetlanguage)¶: Set the target language for this store.

suggestions_in_format = False¶: Indicates if format can store suggestions and alternative translation for a unit

translate(source)¶

Return the translated string for a given source string.

Return type:: String or None

unit_iter()¶: Iterator over all the units in this store.

class translate.storage.html.htmlfile(inputfile=None, callback=None)¶

EMPTY_HTML_ELEMENTS = ['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']¶: An empty element is an element that cannot have any child nodes (i.e., nested elements or text nodes). In HTML, using a closing tag on an empty element is usually invalid. Reference https://developer.mozilla.org/en-US/docs/Glossary/Empty_element

Extensions = None¶: A list of file extentions associated with this store type

Mimetypes = None¶: A list of MIME types associated with this store type

Name = 'Base translation store'¶: The human usable name of this store type

TRANSLATABLE_ATTRIBUTES = ['abbr', 'alt', 'lang', 'summary', 'title', 'value']¶: Text from these HTML attributes will be extracted as translation units. Note: the content attribute of meta tags is a special case.

TRANSLATABLE_ELEMENTS = ['address', 'article', 'aside', 'blockquote', 'caption', 'dd', 'dt', 'div', 'figcaption', 'footer', 'header', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'label', 'li', 'main', 'nav', 'option', 'p', 'pre', 'section', 'td', 'th', 'title']¶: These HTML elements (tags) will be extracted as translation units, unless they lack translatable text content. In case one translatable element is embedded in another, the outer translation unit will be split into the parts before and after the inner translation unit.

TRANSLATABLE_METADATA = ['description', 'keywords']¶: Document metadata from meta elements with these names will be extracted as translation units. Reference https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name

UnitClass¶: alias of htmlunit

add_unit_to_index(unit)¶: Add a unit to source and location idexes.

addsourceunit(source)¶

Add and returns a new unit with the given source string.

Return type:: TranslationUnit

addunit(unit)¶

Append the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

close()¶: Handle any buffered data.

detect_encoding(text: bytes, default_encodings: list[str] | None = None) → tuple[str, str]¶: Try to detect a file encoding from text, using either the chardet lib or by trying to decode the file.

do_encoding(htmlsrc)¶: Return the html text properly encoded based on a charset.

static fallback_detection(text)¶: Simple detection based on BOM in case chardet is not available.

feed(data)¶

Feed data to the parser.

Call this as often as you want, with as little or as much text as you want (may include ‘n’).

findid(id)¶: Find unit with matching id by checking id_index.

findunit(source)¶

Find the unit with the given source string.

Return type:: TranslationUnit or None

findunits(source)¶

Find the units with the given source string.

Return type:: TranslationUnit or None

get_starttag_text()¶: Return full source of start tag: ‘<…>’.

getids()¶: Return a list of unit ids.

getpos()¶: Return current line number and offset.

getprojectstyle()¶: Get the project type for this store.

getsourcelanguage()¶: Get the source language for this store.

gettargetlanguage()¶: Get the target language for this store.

getunits()¶: Return a list of all units in this store.

guess_encoding(htmlsrc)¶

Returns the encoding of the html text.

We look for ‘charset=’ within a meta tag to do this.

handle_charref(name)¶: Handle entries in the form &#NNNN; e.g. ⃡.

handle_entityref(name)¶: Handle named entities of the form &aaaa; e.g. ’.

isempty()¶: Return True if the object doesn’t contain any translation units.

makeindex()¶: Indexes the items in this store. At least .sourceindex should be useful.

property merge_on¶

The matching criterion to use when merging on.

Returns:: The default matching criterion for all the subclasses.
Return type:: string

parse(htmlsrc)¶: Parser to process the given source string.

classmethod parsefile(storefile)¶: Reads the given file (or opens the given filename) and parses back to an object.

classmethod parsestring(storestring)¶: Convert the string representation back to an object.

remove_unit_from_index(unit)¶: Remove a unit from source and locaton indexes.

removeunit(unit)¶

Remove the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

require_index()¶: Make sure source index exists.

reset()¶: Reset this instance. Loses all unprocessed data.

save()¶: Save to the file that data was originally read from, if available.

savefile(storefile)¶: Write the string representation to the given file (or filename).

serialize(out)¶: Converts to a bytes representation that can be parsed back using parsestring(). out should be an open file-like objects to write to.

setprojectstyle(project_style)¶: Set the project type for this store.

setsourcelanguage(sourcelanguage)¶: Set the source language for this store.

settargetlanguage(targetlanguage)¶: Set the target language for this store.

suggestions_in_format = False¶: Indicates if format can store suggestions and alternative translation for a unit

translate(source)¶

Return the translated string for a given source string.

Return type:: String or None

unit_iter()¶: Iterator over all the units in this store.

class translate.storage.html.htmlunit(source=None)¶

A unit of translatable/localisable HTML content.

adderror(errorname, errortext)¶

Adds an error message to this unit.

Parameters:

errorname (string) – A single word to id the error.
errortext (string) – The text describing the error.

addlocation(location)¶: Add one location to the list of locations.

Note

Shouldn’t be implemented if the format doesn’t support it.

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶

Adds a note (comment).

Parameters:

text (string) – Usually just a sentence or two.
origin (string) – Specifies who/where the comment comes from. Origin can be one of the following text strings: - ‘translator’ - ‘developer’, ‘programmer’, ‘source code’ (synonyms)

classmethod buildfromunit(unit)¶

Build a native unit from a foreign unit.

Preserving as much information as possible.

static getcontext()¶: Get the message context.

static geterrors()¶

Get all error messages.

Return type:: Dictionary

getid()¶

A unique identifier for this unit.

Return type:: string
Returns:: an identifier for this unit that is unique in the store

Derived classes should override this in a way that guarantees a unique identifier for each unit in the store.

getlocations()¶

A list of source code locations.

Return type:: List

Note

Shouldn’t be implemented if the format doesn’t support it.

getnotes(origin=None)¶

Returns all notes about this unit.

It will probably be freeform text or something reasonable that can be synthesised by the format. It should not include location comments (see getlocations()).

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

static hasplural()¶: Tells whether or not this specific unit has plural strings.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Used to see if this unit has no source or target string.

Note

This is probably used more to find translatable units, and we might want to move in that direction rather and get rid of this.

static isfuzzy()¶: Indicates whether this unit is fuzzy.

static isheader()¶: Indicates whether this unit is a header.

static isobsolete()¶: Indicate whether a unit is obsolete.

static isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Make a unit obsolete.

markfuzzy(value=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶

Marks the unit to indicate whether it needs review.

Parameters:

needsreview – Defaults to True.
explanation – Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

merge(otherunit, overwrite=False, comments=True, authoritative=False)¶: Do basic format agnostic merging.

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

removenotes(origin=None)¶: Remove all the translator’s notes.

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(context)¶: Set the message context.

setid(value)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

unit_iter()¶: Iterator that only returns this unit.

ical¶

Class that manages iCalender files for translation.

iCalendar files follow the RFC2445 specification.

The iCalendar specification uses the following naming conventions:

Component: an event, journal entry, timezone, etc
Property: a property of a component: summary, description, start time, etc
Attribute: an attribute of a property, e.g. language

The following are localisable in this implementation:

VEVENT component: SUMMARY, DESCRIPTION, COMMENT and LOCATION properties

While other items could be localised this is not seen as important until use cases arise. In such a case simply adjusting the component.name and property.name lists to include these will allow expanded localisation.

LANGUAGE Attribute: While the iCalendar format allows items to have a language attribute this is not used. The reason being that for most of the items that we localise they are only allowed to occur zero or once. Thus ‘summary’ would ideally be present in multiple languages in one file, the format does not allow such multiple entries. This is unfortunate as it prevents the creation of a single multilingual iCalendar file.
Future Format Support: As this format used vobject which supports various formats including vCard it is possible to expand this format to understand those if needed.

class translate.storage.ical.icalfile(inputfile=None, **kwargs)¶

An ical file.

Extensions = None¶: A list of file extentions associated with this store type

Mimetypes = None¶: A list of MIME types associated with this store type

Name = 'Base translation store'¶: The human usable name of this store type

UnitClass¶: alias of icalunit

add_unit_to_index(unit)¶: Add a unit to source and location idexes.

addsourceunit(source)¶

Add and returns a new unit with the given source string.

Return type:: TranslationUnit

addunit(unit)¶

Append the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

detect_encoding(text: bytes, default_encodings: list[str] | None = None) → tuple[str, str]¶: Try to detect a file encoding from text, using either the chardet lib or by trying to decode the file.

static fallback_detection(text)¶: Simple detection based on BOM in case chardet is not available.

findid(id)¶: Find unit with matching id by checking id_index.

findunit(source)¶

Find the unit with the given source string.

Return type:: TranslationUnit or None

findunits(source)¶

Find the units with the given source string.

Return type:: TranslationUnit or None

getids()¶: Return a list of unit ids.

getprojectstyle()¶: Get the project type for this store.

getsourcelanguage()¶: Get the source language for this store.

gettargetlanguage()¶: Get the target language for this store.

getunits()¶: Return a list of all units in this store.

isempty()¶: Return True if the object doesn’t contain any translation units.

makeindex()¶: Indexes the items in this store. At least .sourceindex should be useful.

property merge_on¶

The matching criterion to use when merging on.

Returns:: The default matching criterion for all the subclasses.
Return type:: string

parse(input)¶: Parse the given file or file source string.

classmethod parsefile(storefile)¶: Reads the given file (or opens the given filename) and parses back to an object.

classmethod parsestring(storestring)¶: Convert the string representation back to an object.

remove_unit_from_index(unit)¶: Remove a unit from source and locaton indexes.

removeunit(unit)¶

Remove the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

require_index()¶: Make sure source index exists.

save()¶: Save to the file that data was originally read from, if available.

savefile(storefile)¶: Write the string representation to the given file (or filename).

serialize(out)¶: Converts to a bytes representation that can be parsed back using parsestring(). out should be an open file-like objects to write to.

setprojectstyle(project_style)¶: Set the project type for this store.

setsourcelanguage(sourcelanguage)¶: Set the source language for this store.

settargetlanguage(targetlanguage)¶: Set the target language for this store.

suggestions_in_format = False¶: Indicates if format can store suggestions and alternative translation for a unit

translate(source)¶

Return the translated string for a given source string.

Return type:: String or None

unit_iter()¶: Iterator over all the units in this store.

class translate.storage.ical.icalunit(source=None, **kwargs)¶

An ical entry that is translatable.

adderror(errorname, errortext)¶

Adds an error message to this unit.

Parameters:

errorname (string) – A single word to id the error.
errortext (string) – The text describing the error.

addlocation(location)¶: Add one location to the list of locations.

Note

Shouldn’t be implemented if the format doesn’t support it.

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶

Adds a note (comment).

Parameters:

text (string) – Usually just a sentence or two.
origin (string) – Specifies who/where the comment comes from. Origin can be one of the following text strings: - ‘translator’ - ‘developer’, ‘programmer’, ‘source code’ (synonyms)

classmethod buildfromunit(unit)¶

Build a native unit from a foreign unit.

Preserving as much information as possible.

static getcontext()¶: Get the message context.

static geterrors()¶

Get all error messages.

Return type:: Dictionary

getid()¶

A unique identifier for this unit.

Return type:: string
Returns:: an identifier for this unit that is unique in the store

Derived classes should override this in a way that guarantees a unique identifier for each unit in the store.

getlocations()¶

A list of source code locations.

Return type:: List

Note

Shouldn’t be implemented if the format doesn’t support it.

getnotes(origin=None)¶

Returns all notes about this unit.

It will probably be freeform text or something reasonable that can be synthesised by the format. It should not include location comments (see getlocations()).

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

static hasplural()¶: Tells whether or not this specific unit has plural strings.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Used to see if this unit has no source or target string.

Note

This is probably used more to find translatable units, and we might want to move in that direction rather and get rid of this.

static isfuzzy()¶: Indicates whether this unit is fuzzy.

static isheader()¶: Indicates whether this unit is a header.

static isobsolete()¶: Indicate whether a unit is obsolete.

static isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Make a unit obsolete.

markfuzzy(value=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶

Marks the unit to indicate whether it needs review.

Parameters:

needsreview – Defaults to True.
explanation – Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

merge(otherunit, overwrite=False, comments=True, authoritative=False)¶: Do basic format agnostic merging.

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

removenotes(origin=None)¶: Remove all the translator’s notes.

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(context)¶: Set the message context.

setid(value)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

unit_iter()¶: Iterator that only returns this unit.

ini¶

Class that manages .ini files for translation.

# a comment ; a comment

[Section] a = a string b : a string

class translate.storage.ini.Dialect¶: Base class for differentiating dialect options and functions.

class translate.storage.ini.DialectDefault¶

class translate.storage.ini.DialectInno¶

class translate.storage.ini.inifile(inputfile=None, dialect='default', **kwargs)¶

An INI file.

Extensions = None¶: A list of file extentions associated with this store type

Mimetypes = None¶: A list of MIME types associated with this store type

Name = 'Base translation store'¶: The human usable name of this store type

UnitClass¶: alias of iniunit

add_unit_to_index(unit)¶: Add a unit to source and location idexes.

addsourceunit(source)¶

Add and returns a new unit with the given source string.

Return type:: TranslationUnit

addunit(unit)¶

Append the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

detect_encoding(text: bytes, default_encodings: list[str] | None = None) → tuple[str, str]¶: Try to detect a file encoding from text, using either the chardet lib or by trying to decode the file.

static fallback_detection(text)¶: Simple detection based on BOM in case chardet is not available.

findid(id)¶: Find unit with matching id by checking id_index.

findunit(source)¶

Find the unit with the given source string.

Return type:: TranslationUnit or None

findunits(source)¶

Find the units with the given source string.

Return type:: TranslationUnit or None

getids()¶: Return a list of unit ids.

getprojectstyle()¶: Get the project type for this store.

getsourcelanguage()¶: Get the source language for this store.

gettargetlanguage()¶: Get the target language for this store.

getunits()¶: Return a list of all units in this store.

isempty()¶: Return True if the object doesn’t contain any translation units.

makeindex()¶: Indexes the items in this store. At least .sourceindex should be useful.

property merge_on¶

The matching criterion to use when merging on.

Returns:: The default matching criterion for all the subclasses.
Return type:: string

parse(input)¶: Parse the given file or file source string.

classmethod parsefile(storefile)¶: Reads the given file (or opens the given filename) and parses back to an object.

classmethod parsestring(storestring)¶: Convert the string representation back to an object.

remove_unit_from_index(unit)¶: Remove a unit from source and locaton indexes.

removeunit(unit)¶

Remove the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

require_index()¶: Make sure source index exists.

save()¶: Save to the file that data was originally read from, if available.

savefile(storefile)¶: Write the string representation to the given file (or filename).

serialize(out)¶: Converts to a bytes representation that can be parsed back using parsestring(). out should be an open file-like objects to write to.

setprojectstyle(project_style)¶: Set the project type for this store.

setsourcelanguage(sourcelanguage)¶: Set the source language for this store.

settargetlanguage(targetlanguage)¶: Set the target language for this store.

suggestions_in_format = False¶: Indicates if format can store suggestions and alternative translation for a unit

translate(source)¶

Return the translated string for a given source string.

Return type:: String or None

unit_iter()¶: Iterator over all the units in this store.

class translate.storage.ini.iniunit(source=None, **kwargs)¶

A INI file entry.

adderror(errorname, errortext)¶

Adds an error message to this unit.

Parameters:

errorname (string) – A single word to id the error.
errortext (string) – The text describing the error.

addlocation(location)¶: Add one location to the list of locations.

Note

Shouldn’t be implemented if the format doesn’t support it.

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶

Adds a note (comment).

Parameters:

text (string) – Usually just a sentence or two.
origin (string) – Specifies who/where the comment comes from. Origin can be one of the following text strings: - ‘translator’ - ‘developer’, ‘programmer’, ‘source code’ (synonyms)

classmethod buildfromunit(unit)¶

Build a native unit from a foreign unit.

Preserving as much information as possible.

static getcontext()¶: Get the message context.

static geterrors()¶

Get all error messages.

Return type:: Dictionary

getid()¶

A unique identifier for this unit.

Return type:: string
Returns:: an identifier for this unit that is unique in the store

Derived classes should override this in a way that guarantees a unique identifier for each unit in the store.

getlocations()¶

A list of source code locations.

Return type:: List

Note

Shouldn’t be implemented if the format doesn’t support it.

getnotes(origin=None)¶

Returns all notes about this unit.

It will probably be freeform text or something reasonable that can be synthesised by the format. It should not include location comments (see getlocations()).

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

static hasplural()¶: Tells whether or not this specific unit has plural strings.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Used to see if this unit has no source or target string.

Note

This is probably used more to find translatable units, and we might want to move in that direction rather and get rid of this.

static isfuzzy()¶: Indicates whether this unit is fuzzy.

static isheader()¶: Indicates whether this unit is a header.

static isobsolete()¶: Indicate whether a unit is obsolete.

static isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Make a unit obsolete.

markfuzzy(value=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶

Marks the unit to indicate whether it needs review.

Parameters:

needsreview – Defaults to True.
explanation – Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

merge(otherunit, overwrite=False, comments=True, authoritative=False)¶: Do basic format agnostic merging.

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

removenotes(origin=None)¶: Remove all the translator’s notes.

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(context)¶: Set the message context.

setid(value)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

unit_iter()¶: Iterator that only returns this unit.

translate.storage.ini.register_dialect(dialect)¶: Decorator that registers the dialect.

jsonl10n¶

Class that manages JSON data files for translation.

JSON is an acronym for JavaScript Object Notation, it is an open standard designed for human-readable data interchange.

JSON basic types:

Number (integer or real)
String (double-quoted Unicode with backslash escaping)
Boolean (true or false)
Array (an ordered sequence of values, comma-separated and enclosed in square brackets)
Object (a collection of key:value pairs, comma-separated and enclosed in curly braces)
null

Example:¶

{
     "firstName": "John",
     "lastName": "Smith",
     "age": 25,
     "address": {
         "streetAddress": "21 2nd Street",
         "city": "New York",
         "state": "NY",
         "postalCode": "10021"
     },
     "phoneNumber": [
         {
           "type": "home",
           "number": "212 555-1234"
         },
         {
           "type": "fax",
           "number": "646 555-4567"
         }
     ]
}

Todo:¶

Handle \u and other escapes in Unicode
Manage data type storage and conversion. True –> “True” –> True

class translate.storage.jsonl10n.ARBJsonFile(inputfile=None, filter=None, **kwargs)¶

ARB JSON file.

See following URLs for doc:

https://github.com/google/app-resource-bundle/wiki/ApplicationResourceBundleSpecification https://docs.flutter.dev/development/accessibility-and-localization/internationalization#dart-tools

Extensions = None¶: A list of file extentions associated with this store type

Mimetypes = None¶: A list of MIME types associated with this store type

Name = 'Base translation store'¶: The human usable name of this store type

UnitClass¶: alias of ARBJsonUnit

add_unit_to_index(unit)¶: Add a unit to source and location idexes.

addsourceunit(source)¶

Add and returns a new unit with the given source string.

Return type:: TranslationUnit

addunit(unit)¶

Append the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

detect_encoding(text: bytes, default_encodings: list[str] | None = None) → tuple[str, str]¶: Try to detect a file encoding from text, using either the chardet lib or by trying to decode the file.

static fallback_detection(text)¶: Simple detection based on BOM in case chardet is not available.

findid(id)¶: Find unit with matching id by checking id_index.

findunit(source)¶

Find the unit with the given source string.

Return type:: TranslationUnit or None

findunits(source)¶

Find the units with the given source string.

Return type:: TranslationUnit or None

getids()¶: Return a list of unit ids.

getprojectstyle()¶: Get the project type for this store.

getsourcelanguage()¶: Get the source language for this store.

gettargetlanguage()¶: Get the target language for this store.

getunits()¶: Return a list of all units in this store.

isempty()¶: Return True if the object doesn’t contain any translation units.

makeindex()¶: Indexes the items in this store. At least .sourceindex should be useful.

property merge_on¶

The matching criterion to use when merging on.

Returns:: The default matching criterion for all the subclasses.
Return type:: string

parse(input)¶: Parse the given file or file source string.

classmethod parsefile(storefile)¶: Reads the given file (or opens the given filename) and parses back to an object.

classmethod parsestring(storestring)¶: Convert the string representation back to an object.

remove_unit_from_index(unit)¶: Remove a unit from source and locaton indexes.

removeunit(unit)¶

Remove the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

require_index()¶: Make sure source index exists.

save()¶: Save to the file that data was originally read from, if available.

savefile(storefile)¶: Write the string representation to the given file (or filename).

serialize(out)¶: Converts to a bytes representation that can be parsed back using parsestring(). out should be an open file-like objects to write to.

setprojectstyle(project_style)¶: Set the project type for this store.

setsourcelanguage(sourcelanguage)¶: Set the source language for this store.

settargetlanguage(targetlanguage)¶: Set the target language for this store.

suggestions_in_format = False¶: Indicates if format can store suggestions and alternative translation for a unit

translate(source)¶

Return the translated string for a given source string.

Return type:: String or None

unit_iter()¶: Iterator over all the units in this store.

class translate.storage.jsonl10n.ARBJsonUnit(source=None, item=None, notes=None, placeholders=None, metadata=None, **kwargs)¶

adderror(errorname, errortext)¶

Adds an error message to this unit.

Parameters:

errorname (string) – A single word to id the error.
errortext (string) – The text describing the error.

addlocation(location)¶: Add one location to the list of locations.

Note

Shouldn’t be implemented if the format doesn’t support it.

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶

Adds a note (comment).

Parameters:

text (string) – Usually just a sentence or two.
origin (string) – Specifies who/where the comment comes from. Origin can be one of the following text strings: - ‘translator’ - ‘developer’, ‘programmer’, ‘source code’ (synonyms)

classmethod buildfromunit(unit)¶

Build a native unit from a foreign unit.

Preserving as much information as possible.

static getcontext()¶: Get the message context.

static geterrors()¶

Get all error messages.

Return type:: Dictionary

getid()¶

A unique identifier for this unit.

Return type:: string
Returns:: an identifier for this unit that is unique in the store

Derived classes should override this in a way that guarantees a unique identifier for each unit in the store.

getlocations()¶

A list of source code locations.

Return type:: List

Note

Shouldn’t be implemented if the format doesn’t support it.

getnotes(origin=None)¶

Returns all notes about this unit.

It will probably be freeform text or something reasonable that can be synthesised by the format. It should not include location comments (see getlocations()).

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

getvalue()¶: Returns dictionary for serialization.

static hasplural()¶: Tells whether or not this specific unit has plural strings.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Used to see if this unit has no source or target string.

Note

This is probably used more to find translatable units, and we might want to move in that direction rather and get rid of this.

static isfuzzy()¶: Indicates whether this unit is fuzzy.

isheader()¶: Indicates whether this unit is a header.

static isobsolete()¶: Indicate whether a unit is obsolete.

static isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Make a unit obsolete.

markfuzzy(value=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶

Marks the unit to indicate whether it needs review.

Parameters:

needsreview – Defaults to True.
explanation – Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

merge(otherunit, overwrite=False, comments=True, authoritative=False)¶: Do basic format agnostic merging.

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

removenotes(origin=None)¶: Remove all the translator’s notes.

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(context)¶: Set the message context.

setid(value, unitid=None)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

unit_iter()¶: Iterator that only returns this unit.

class translate.storage.jsonl10n.BaseJsonUnit(source=None, item=None, notes=None, placeholders=None, **kwargs)¶

A JSON entry.

adderror(errorname, errortext)¶

Adds an error message to this unit.

Parameters:

errorname (string) – A single word to id the error.
errortext (string) – The text describing the error.

addlocation(location)¶: Add one location to the list of locations.

Note

Shouldn’t be implemented if the format doesn’t support it.

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶

Adds a note (comment).

Parameters:

text (string) – Usually just a sentence or two.
origin (string) – Specifies who/where the comment comes from. Origin can be one of the following text strings: - ‘translator’ - ‘developer’, ‘programmer’, ‘source code’ (synonyms)

classmethod buildfromunit(unit)¶

Build a native unit from a foreign unit.

Preserving as much information as possible.

static getcontext()¶: Get the message context.

static geterrors()¶

Get all error messages.

Return type:: Dictionary

getid()¶

A unique identifier for this unit.

Return type:: string
Returns:: an identifier for this unit that is unique in the store

Derived classes should override this in a way that guarantees a unique identifier for each unit in the store.

getlocations()¶

A list of source code locations.

Return type:: List

Note

Shouldn’t be implemented if the format doesn’t support it.

getnotes(origin=None)¶

Returns all notes about this unit.

It will probably be freeform text or something reasonable that can be synthesised by the format. It should not include location comments (see getlocations()).

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

getvalue()¶: Returns dictionary for serialization.

static hasplural()¶: Tells whether or not this specific unit has plural strings.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Used to see if this unit has no source or target string.

Note

This is probably used more to find translatable units, and we might want to move in that direction rather and get rid of this.

static isfuzzy()¶: Indicates whether this unit is fuzzy.

static isheader()¶: Indicates whether this unit is a header.

static isobsolete()¶: Indicate whether a unit is obsolete.

static isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Make a unit obsolete.

markfuzzy(value=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶

Marks the unit to indicate whether it needs review.

Parameters:

needsreview – Defaults to True.
explanation – Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

merge(otherunit, overwrite=False, comments=True, authoritative=False)¶: Do basic format agnostic merging.

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

removenotes(origin=None)¶: Remove all the translator’s notes.

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(context)¶: Set the message context.

setid(value, unitid=None)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

unit_iter()¶: Iterator that only returns this unit.

class translate.storage.jsonl10n.FlatI18NextV4File(inputfile=None, filter=None, **kwargs)¶

Flat json file with support of i18next v4 format plurals.

See https://www.i18next.com/

Extensions = None¶: A list of file extentions associated with this store type

Mimetypes = None¶: A list of MIME types associated with this store type

Name = 'Base translation store'¶: The human usable name of this store type

UnitClass¶: alias of FlatI18NextV4Unit

add_unit_to_index(unit)¶: Add a unit to source and location idexes.

addsourceunit(source)¶

Add and returns a new unit with the given source string.

Return type:: TranslationUnit

addunit(unit)¶

Append the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

detect_encoding(text: bytes, default_encodings: list[str] | None = None) → tuple[str, str]¶: Try to detect a file encoding from text, using either the chardet lib or by trying to decode the file.

static fallback_detection(text)¶: Simple detection based on BOM in case chardet is not available.

findid(id)¶: Find unit with matching id by checking id_index.

findunit(source)¶

Find the unit with the given source string.

Return type:: TranslationUnit or None

findunits(source)¶

Find the units with the given source string.

Return type:: TranslationUnit or None

getids()¶: Return a list of unit ids.

getprojectstyle()¶: Get the project type for this store.

getsourcelanguage()¶: Get the source language for this store.

gettargetlanguage()¶: Get the target language for this store.

getunits()¶: Return a list of all units in this store.

isempty()¶: Return True if the object doesn’t contain any translation units.

makeindex()¶: Indexes the items in this store. At least .sourceindex should be useful.

property merge_on¶

The matching criterion to use when merging on.

Returns:: The default matching criterion for all the subclasses.
Return type:: string

parse(input)¶: Parse the given file or file source string.

classmethod parsefile(storefile)¶: Reads the given file (or opens the given filename) and parses back to an object.

classmethod parsestring(storestring)¶: Convert the string representation back to an object.

remove_unit_from_index(unit)¶: Remove a unit from source and locaton indexes.

removeunit(unit)¶

Remove the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

require_index()¶: Make sure source index exists.

save()¶: Save to the file that data was originally read from, if available.

savefile(storefile)¶: Write the string representation to the given file (or filename).

serialize(out)¶: Converts to a bytes representation that can be parsed back using parsestring(). out should be an open file-like objects to write to.

setprojectstyle(project_style)¶: Set the project type for this store.

setsourcelanguage(sourcelanguage)¶: Set the source language for this store.

settargetlanguage(targetlanguage)¶: Set the target language for this store.

suggestions_in_format = False¶: Indicates if format can store suggestions and alternative translation for a unit

translate(source)¶

Return the translated string for a given source string.

Return type:: String or None

unit_iter()¶: Iterator over all the units in this store.

class translate.storage.jsonl10n.FlatI18NextV4Unit(source=None, item=None, notes=None, placeholders=None, **kwargs)¶

adderror(errorname, errortext)¶

Adds an error message to this unit.

Parameters:

errorname (string) – A single word to id the error.
errortext (string) – The text describing the error.

addlocation(location)¶: Add one location to the list of locations.

Note

Shouldn’t be implemented if the format doesn’t support it.

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶

Adds a note (comment).

Parameters:

text (string) – Usually just a sentence or two.
origin (string) – Specifies who/where the comment comes from. Origin can be one of the following text strings: - ‘translator’ - ‘developer’, ‘programmer’, ‘source code’ (synonyms)

classmethod buildfromunit(unit)¶

Build a native unit from a foreign unit.

Preserving as much information as possible.

static getcontext()¶: Get the message context.

static geterrors()¶

Get all error messages.

Return type:: Dictionary

getid()¶

A unique identifier for this unit.

Return type:: string
Returns:: an identifier for this unit that is unique in the store

Derived classes should override this in a way that guarantees a unique identifier for each unit in the store.

getlocations()¶

A list of source code locations.

Return type:: List

Note

Shouldn’t be implemented if the format doesn’t support it.

getnotes(origin=None)¶

Returns all notes about this unit.

It will probably be freeform text or something reasonable that can be synthesised by the format. It should not include location comments (see getlocations()).

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

getvalue()¶: Returns dictionary for serialization.

static hasplural()¶: Tells whether or not this specific unit has plural strings.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Used to see if this unit has no source or target string.

Note

This is probably used more to find translatable units, and we might want to move in that direction rather and get rid of this.

static isfuzzy()¶: Indicates whether this unit is fuzzy.

static isheader()¶: Indicates whether this unit is a header.

static isobsolete()¶: Indicate whether a unit is obsolete.

static isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Make a unit obsolete.

markfuzzy(value=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶

Marks the unit to indicate whether it needs review.

Parameters:

needsreview – Defaults to True.
explanation – Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

merge(otherunit, overwrite=False, comments=True, authoritative=False)¶: Do basic format agnostic merging.

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

removenotes(origin=None)¶: Remove all the translator’s notes.

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(context)¶: Set the message context.

setid(value, unitid=None)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

unit_iter()¶: Iterator that only returns this unit.

class translate.storage.jsonl10n.FlatJsonUnit(source=None, item=None, notes=None, placeholders=None, **kwargs)¶

adderror(errorname, errortext)¶

Adds an error message to this unit.

Parameters:

errorname (string) – A single word to id the error.
errortext (string) – The text describing the error.

addlocation(location)¶: Add one location to the list of locations.

Note

Shouldn’t be implemented if the format doesn’t support it.

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶

Adds a note (comment).

Parameters:

text (string) – Usually just a sentence or two.
origin (string) – Specifies who/where the comment comes from. Origin can be one of the following text strings: - ‘translator’ - ‘developer’, ‘programmer’, ‘source code’ (synonyms)

classmethod buildfromunit(unit)¶

Build a native unit from a foreign unit.

Preserving as much information as possible.

static getcontext()¶: Get the message context.

static geterrors()¶

Get all error messages.

Return type:: Dictionary

getid()¶

A unique identifier for this unit.

Return type:: string
Returns:: an identifier for this unit that is unique in the store

Derived classes should override this in a way that guarantees a unique identifier for each unit in the store.

getlocations()¶

A list of source code locations.

Return type:: List

Note

Shouldn’t be implemented if the format doesn’t support it.

getnotes(origin=None)¶

Returns all notes about this unit.

It will probably be freeform text or something reasonable that can be synthesised by the format. It should not include location comments (see getlocations()).

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

getvalue()¶: Returns dictionary for serialization.

static hasplural()¶: Tells whether or not this specific unit has plural strings.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Used to see if this unit has no source or target string.

Note

This is probably used more to find translatable units, and we might want to move in that direction rather and get rid of this.

static isfuzzy()¶: Indicates whether this unit is fuzzy.

static isheader()¶: Indicates whether this unit is a header.

static isobsolete()¶: Indicate whether a unit is obsolete.

static isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Make a unit obsolete.

markfuzzy(value=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶

Marks the unit to indicate whether it needs review.

Parameters:

needsreview – Defaults to True.
explanation – Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

merge(otherunit, overwrite=False, comments=True, authoritative=False)¶: Do basic format agnostic merging.

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

removenotes(origin=None)¶: Remove all the translator’s notes.

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(context)¶: Set the message context.

setid(value, unitid=None)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

unit_iter()¶: Iterator that only returns this unit.

class translate.storage.jsonl10n.FormatJSJsonFile(inputfile=None, filter=None, **kwargs)¶

FormatJS JSON file.

See following URLs for doc:

https://formatjs.io/docs/getting-started/message-extraction/

Extensions = None¶: A list of file extentions associated with this store type

Mimetypes = None¶: A list of MIME types associated with this store type

Name = 'Base translation store'¶: The human usable name of this store type

UnitClass¶: alias of FormatJSJsonUnit

add_unit_to_index(unit)¶: Add a unit to source and location idexes.

addsourceunit(source)¶

Add and returns a new unit with the given source string.

Return type:: TranslationUnit

addunit(unit)¶

Append the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

detect_encoding(text: bytes, default_encodings: list[str] | None = None) → tuple[str, str]¶: Try to detect a file encoding from text, using either the chardet lib or by trying to decode the file.

static fallback_detection(text)¶: Simple detection based on BOM in case chardet is not available.

findid(id)¶: Find unit with matching id by checking id_index.

findunit(source)¶

Find the unit with the given source string.

Return type:: TranslationUnit or None

findunits(source)¶

Find the units with the given source string.

Return type:: TranslationUnit or None

getids()¶: Return a list of unit ids.

getprojectstyle()¶: Get the project type for this store.

getsourcelanguage()¶: Get the source language for this store.

gettargetlanguage()¶: Get the target language for this store.

getunits()¶: Return a list of all units in this store.

isempty()¶: Return True if the object doesn’t contain any translation units.

makeindex()¶: Indexes the items in this store. At least .sourceindex should be useful.

property merge_on¶

The matching criterion to use when merging on.

Returns:: The default matching criterion for all the subclasses.
Return type:: string

parse(input)¶: Parse the given file or file source string.

classmethod parsefile(storefile)¶: Reads the given file (or opens the given filename) and parses back to an object.

classmethod parsestring(storestring)¶: Convert the string representation back to an object.

remove_unit_from_index(unit)¶: Remove a unit from source and locaton indexes.

removeunit(unit)¶

Remove the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

require_index()¶: Make sure source index exists.

save()¶: Save to the file that data was originally read from, if available.

savefile(storefile)¶: Write the string representation to the given file (or filename).

serialize(out)¶: Converts to a bytes representation that can be parsed back using parsestring(). out should be an open file-like objects to write to.

setprojectstyle(project_style)¶: Set the project type for this store.

setsourcelanguage(sourcelanguage)¶: Set the source language for this store.

settargetlanguage(targetlanguage)¶: Set the target language for this store.

suggestions_in_format = False¶: Indicates if format can store suggestions and alternative translation for a unit

translate(source)¶

Return the translated string for a given source string.

Return type:: String or None

unit_iter()¶: Iterator over all the units in this store.

class translate.storage.jsonl10n.FormatJSJsonUnit(source=None, item=None, notes=None, placeholders=None, **kwargs)¶

adderror(errorname, errortext)¶

Adds an error message to this unit.

Parameters:

errorname (string) – A single word to id the error.
errortext (string) – The text describing the error.

addlocation(location)¶: Add one location to the list of locations.

Note

Shouldn’t be implemented if the format doesn’t support it.

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶

Adds a note (comment).

Parameters:

text (string) – Usually just a sentence or two.
origin (string) – Specifies who/where the comment comes from. Origin can be one of the following text strings: - ‘translator’ - ‘developer’, ‘programmer’, ‘source code’ (synonyms)

classmethod buildfromunit(unit)¶

Build a native unit from a foreign unit.

Preserving as much information as possible.

static getcontext()¶: Get the message context.

static geterrors()¶

Get all error messages.

Return type:: Dictionary

getid()¶

A unique identifier for this unit.

Return type:: string
Returns:: an identifier for this unit that is unique in the store

Derived classes should override this in a way that guarantees a unique identifier for each unit in the store.

getlocations()¶

A list of source code locations.

Return type:: List

Note

Shouldn’t be implemented if the format doesn’t support it.

getnotes(origin=None)¶

Returns all notes about this unit.

It will probably be freeform text or something reasonable that can be synthesised by the format. It should not include location comments (see getlocations()).

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

getvalue()¶: Returns dictionary for serialization.

static hasplural()¶: Tells whether or not this specific unit has plural strings.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Used to see if this unit has no source or target string.

Note

This is probably used more to find translatable units, and we might want to move in that direction rather and get rid of this.

static isfuzzy()¶: Indicates whether this unit is fuzzy.

static isheader()¶: Indicates whether this unit is a header.

static isobsolete()¶: Indicate whether a unit is obsolete.

static isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Make a unit obsolete.

markfuzzy(value=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶

Marks the unit to indicate whether it needs review.

Parameters:

needsreview – Defaults to True.
explanation – Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

merge(otherunit, overwrite=False, comments=True, authoritative=False)¶: Do basic format agnostic merging.

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

removenotes(origin=None)¶: Remove all the translator’s notes.

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(context)¶: Set the message context.

setid(value, unitid=None)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

unit_iter()¶: Iterator that only returns this unit.

class translate.storage.jsonl10n.GoI18NJsonFile(inputfile=None, filter=None, **kwargs)¶

go-i18n JSON file.

See following URLs for doc:

https://github.com/nicksnyder/go-i18n/tree/v1 https://pkg.go.dev/github.com/nicksnyder/go-i18n

Extensions = None¶: A list of file extentions associated with this store type

Mimetypes = None¶: A list of MIME types associated with this store type

Name = 'Base translation store'¶: The human usable name of this store type

UnitClass¶: alias of GoI18NJsonUnit

add_unit_to_index(unit)¶: Add a unit to source and location idexes.

addsourceunit(source)¶

Add and returns a new unit with the given source string.

Return type:: TranslationUnit

addunit(unit)¶

Append the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

detect_encoding(text: bytes, default_encodings: list[str] | None = None) → tuple[str, str]¶: Try to detect a file encoding from text, using either the chardet lib or by trying to decode the file.

static fallback_detection(text)¶: Simple detection based on BOM in case chardet is not available.

findid(id)¶: Find unit with matching id by checking id_index.

findunit(source)¶

Find the unit with the given source string.

Return type:: TranslationUnit or None

findunits(source)¶

Find the units with the given source string.

Return type:: TranslationUnit or None

getids()¶: Return a list of unit ids.

getprojectstyle()¶: Get the project type for this store.

getsourcelanguage()¶: Get the source language for this store.

gettargetlanguage()¶: Get the target language for this store.

getunits()¶: Return a list of all units in this store.

isempty()¶: Return True if the object doesn’t contain any translation units.

makeindex()¶: Indexes the items in this store. At least .sourceindex should be useful.

property merge_on¶

The matching criterion to use when merging on.

Returns:: The default matching criterion for all the subclasses.
Return type:: string

parse(input)¶: Parse the given file or file source string.

classmethod parsefile(storefile)¶: Reads the given file (or opens the given filename) and parses back to an object.

classmethod parsestring(storestring)¶: Convert the string representation back to an object.

remove_unit_from_index(unit)¶: Remove a unit from source and locaton indexes.

removeunit(unit)¶

Remove the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

require_index()¶: Make sure source index exists.

save()¶: Save to the file that data was originally read from, if available.

savefile(storefile)¶: Write the string representation to the given file (or filename).

serialize(out)¶: Converts to a bytes representation that can be parsed back using parsestring(). out should be an open file-like objects to write to.

setprojectstyle(project_style)¶: Set the project type for this store.

setsourcelanguage(sourcelanguage)¶: Set the source language for this store.

settargetlanguage(targetlanguage)¶: Set the target language for this store.

suggestions_in_format = False¶: Indicates if format can store suggestions and alternative translation for a unit

translate(source)¶

Return the translated string for a given source string.

Return type:: String or None

unit_iter()¶: Iterator over all the units in this store.

class translate.storage.jsonl10n.GoI18NJsonUnit(source=None, item=None, notes=None, placeholders=None, **kwargs)¶

adderror(errorname, errortext)¶

Adds an error message to this unit.

Parameters:

errorname (string) – A single word to id the error.
errortext (string) – The text describing the error.

addlocation(location)¶: Add one location to the list of locations.

Note

Shouldn’t be implemented if the format doesn’t support it.

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶

Adds a note (comment).

Parameters:

text (string) – Usually just a sentence or two.
origin (string) – Specifies who/where the comment comes from. Origin can be one of the following text strings: - ‘translator’ - ‘developer’, ‘programmer’, ‘source code’ (synonyms)

classmethod buildfromunit(unit)¶

Build a native unit from a foreign unit.

Preserving as much information as possible.

static getcontext()¶: Get the message context.

static geterrors()¶

Get all error messages.

Return type:: Dictionary

getid()¶

A unique identifier for this unit.

Return type:: string
Returns:: an identifier for this unit that is unique in the store

Derived classes should override this in a way that guarantees a unique identifier for each unit in the store.

getlocations()¶

A list of source code locations.

Return type:: List

Note

Shouldn’t be implemented if the format doesn’t support it.

getnotes(origin=None)¶

Returns all notes about this unit.

It will probably be freeform text or something reasonable that can be synthesised by the format. It should not include location comments (see getlocations()).

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

getvalue()¶: Returns dictionary for serialization.

static hasplural()¶: Tells whether or not this specific unit has plural strings.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Used to see if this unit has no source or target string.

Note

This is probably used more to find translatable units, and we might want to move in that direction rather and get rid of this.

static isfuzzy()¶: Indicates whether this unit is fuzzy.

static isheader()¶: Indicates whether this unit is a header.

static isobsolete()¶: Indicate whether a unit is obsolete.

static isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Make a unit obsolete.

markfuzzy(value=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶

Marks the unit to indicate whether it needs review.

Parameters:

needsreview – Defaults to True.
explanation – Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

merge(otherunit, overwrite=False, comments=True, authoritative=False)¶: Do basic format agnostic merging.

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

removenotes(origin=None)¶: Remove all the translator’s notes.

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(context)¶: Set the message context.

setid(value, unitid=None)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

unit_iter()¶: Iterator that only returns this unit.

class translate.storage.jsonl10n.GoI18NV2JsonFile(inputfile=None, filter=None, **kwargs)¶

go-i18n v2 JSON file.

See following URLs for doc:

https://github.com/nicksnyder/go-i18n https://pkg.go.dev/github.com/nicksnyder/go-i18n/v2

Extensions = None¶: A list of file extentions associated with this store type

Mimetypes = None¶: A list of MIME types associated with this store type

Name = 'Base translation store'¶: The human usable name of this store type

UnitClass¶: alias of GoI18NV2JsonUnit

add_unit_to_index(unit)¶: Add a unit to source and location idexes.

addsourceunit(source)¶

Add and returns a new unit with the given source string.

Return type:: TranslationUnit

addunit(unit)¶

Append the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

detect_encoding(text: bytes, default_encodings: list[str] | None = None) → tuple[str, str]¶: Try to detect a file encoding from text, using either the chardet lib or by trying to decode the file.

static fallback_detection(text)¶: Simple detection based on BOM in case chardet is not available.

findid(id)¶: Find unit with matching id by checking id_index.

findunit(source)¶

Find the unit with the given source string.

Return type:: TranslationUnit or None

findunits(source)¶

Find the units with the given source string.

Return type:: TranslationUnit or None

getids()¶: Return a list of unit ids.

getprojectstyle()¶: Get the project type for this store.

getsourcelanguage()¶: Get the source language for this store.

gettargetlanguage()¶: Get the target language for this store.

getunits()¶: Return a list of all units in this store.

isempty()¶: Return True if the object doesn’t contain any translation units.

makeindex()¶: Indexes the items in this store. At least .sourceindex should be useful.

property merge_on¶

The matching criterion to use when merging on.

Returns:: The default matching criterion for all the subclasses.
Return type:: string

parse(input)¶: Parse the given file or file source string.

classmethod parsefile(storefile)¶: Reads the given file (or opens the given filename) and parses back to an object.

classmethod parsestring(storestring)¶: Convert the string representation back to an object.

remove_unit_from_index(unit)¶: Remove a unit from source and locaton indexes.

removeunit(unit)¶

Remove the given unit to the object’s list of units.

This method should always be used rather than trying to modify the list manually.

Parameters:: unit (TranslationUnit) – The unit that will be added.

require_index()¶: Make sure source index exists.

save()¶: Save to the file that data was originally read from, if available.

savefile(storefile)¶: Write the string representation to the given file (or filename).

serialize(out)¶: Converts to a bytes representation that can be parsed back using parsestring(). out should be an open file-like objects to write to.

setprojectstyle(project_style)¶: Set the project type for this store.

setsourcelanguage(sourcelanguage)¶: Set the source language for this store.

settargetlanguage(targetlanguage)¶: Set the target language for this store.

suggestions_in_format = False¶: Indicates if format can store suggestions and alternative translation for a unit

translate(source)¶

Return the translated string for a given source string.

Return type:: String or None

unit_iter()¶: Iterator over all the units in this store.

class translate.storage.jsonl10n.GoI18NV2JsonUnit(source=None, item=None, notes=None, placeholders=None, **kwargs)¶

adderror(errorname, errortext)¶

Adds an error message to this unit.

Parameters:

errorname (string) – A single word to id the error.
errortext (string) – The text describing the error.

addlocation(location)¶: Add one location to the list of locations.

Note

Shouldn’t be implemented if the format doesn’t support it.

addlocations(location)¶: Add a location or a list of locations.

Note

Most classes shouldn’t need to implement this, but should rather implement TranslationUnit.addlocation().

Warning

This method might be removed in future.

addnote(text, origin=None, position='append')¶

Adds a note (comment).

Parameters:

text (string) – Usually just a sentence or two.
origin (string) – Specifies who/where the comment comes from. Origin can be one of the following text strings: - ‘translator’ - ‘developer’, ‘programmer’, ‘source code’ (synonyms)

classmethod buildfromunit(unit)¶

Build a native unit from a foreign unit.

Preserving as much information as possible.

static getcontext()¶: Get the message context.

static geterrors()¶

Get all error messages.

Return type:: Dictionary

getid()¶

A unique identifier for this unit.

Return type:: string
Returns:: an identifier for this unit that is unique in the store

Derived classes should override this in a way that guarantees a unique identifier for each unit in the store.

getlocations()¶

A list of source code locations.

Return type:: List

Note

Shouldn’t be implemented if the format doesn’t support it.

getnotes(origin=None)¶

Returns all notes about this unit.

It will probably be freeform text or something reasonable that can be synthesised by the format. It should not include location comments (see getlocations()).

gettargetlen()¶

Returns the length of the target string.

Return type:: Integer

Note

Plural forms might be combined.

getunits()¶: This unit in a list.

getvalue()¶: Returns dictionary for serialization.

static hasplural()¶: Tells whether or not this specific unit has plural strings.

infer_state()¶: Empty method that should be overridden in sub-classes to infer the current state(_n) of the unit from its current state.

isblank()¶: Used to see if this unit has no source or target string.

Note

This is probably used more to find translatable units, and we might want to move in that direction rather and get rid of this.

static isfuzzy()¶: Indicates whether this unit is fuzzy.

static isheader()¶: Indicates whether this unit is a header.

static isobsolete()¶: Indicate whether a unit is obsolete.

static isreview()¶: Indicates whether this unit needs review.

istranslatable()¶

Indicates whether this unit can be translated.

This should be used to distinguish real units for translation from header, obsolete, binary or other blank units.

istranslated()¶

Indicates whether this unit is translated.

This should be used rather than deducing it from .target, to ensure that other classes can implement more functionality (as XLIFF does).

makeobsolete()¶: Make a unit obsolete.

markfuzzy(value=True)¶: Marks the unit as fuzzy or not.

markreviewneeded(needsreview=True, explanation=None)¶

Marks the unit to indicate whether it needs review.

Parameters:

needsreview – Defaults to True.
explanation – Adds an optional explanation as a note.

marktranslatable(value: bool) → None¶: Marks the unit as translateable or not.

merge(otherunit, overwrite=False, comments=True, authoritative=False)¶: Do basic format agnostic merging.

multistring_to_rich(mulstring)¶

Convert a multistring to a list of “rich” string trees.

>>> target = multistring(['foo', 'bar', 'baz'])
>>> TranslationUnit.multistring_to_rich(target)
[<StringElem([<StringElem(['foo'])>])>,
 <StringElem([<StringElem(['bar'])>])>,
 <StringElem([<StringElem(['baz'])>])>]

removenotes(origin=None)¶: Remove all the translator’s notes.

rich_parsers = []¶: A list of functions to use for parsing a string into a rich string tree.

property rich_source¶: See also

rich_to_multistring(), multistring_to_rich().

property rich_target¶: See also

rich_to_multistring(), multistring_to_rich().

classmethod rich_to_multistring(elem_list)¶

Convert a “rich” string tree to a multistring.

>>> from translate.storage.placeables.interfaces import X
>>> rich = [StringElem(['foo', X(id='xxx', sub=[' ']), 'bar'])]
>>> TranslationUnit.rich_to_multistring(rich)
multistring('foo bar')

setcontext(context)¶: Set the message context.

setid(value, unitid=None)¶

Sets the unique identified for this unit.

only implemented if format allows ids independant from other unit properties like source or context

static sync_plural_count(target: list[str] | str | multistring, plural_tags: list[str]) → list[str]¶: Ensure that plural count in string matches tags definition.

unit_iter()¶: Iterator that only returns this unit.

class translate.storage.jsonl10n.GoTextJsonFile(inputfile=None, filter=None, **kwargs)