Utilities for accessing Path of Exile’s translation file format.

Overview

Path	PyPoE/poe/file/translations.py
Version	1.0.0a0
Revision	$Id: 51bc94be6c483a5b224ccc809e5ab4ae08bbdb68 $
Author	Omega_K2

Description

Utilities for parsing and using GGG translations.

The translation GGG provides are generally suffixed by _descriptions.txt and can be found in the MetaData/StatDescriptions/ folder.

Agreement

See PyPoE/LICENSE

Todo

optimize __hash__ very slow atm; or remove, but it is needed for the diffs reverse for non-number values?

Fix empty translation strings

passive_skill_stat_descriptions: tolerance vs missing stuff.

Documentation

Public API

API for common and every day use.

Most of the time you’ll just want to import the TranslationFile or TranslationFileCache classes and work with the instantiated TranslationFile.get_translation() and TranslationFile.reverse_translation() methods.

The result formats TranslationResult and TranslationReverseResult provide optional wrappers around the function results that contain extra information and utility methods.

class PyPoE.poe.file.translations.TranslationFile(file_path=None, base_dir=None, parent=None)

Bases: PyPoE.poe.file.shared.AbstractFileReadOnly

Translation file reader.

Translation files can be found in the following folder in the content.ggpk:

Metadata/StatDescriptions/xxx_descriptions.txt

Variables:

• translations (list[Translation]) – List of parsed Translation instances (in order)
• translations_hash (dict[str, list[Translation]]) –

  Mapping of parsed Translation instances with their id(s) as key.

  Each value is a list of Translation instances, even if there is only one.

__init__(file_path=None, base_dir=None, parent=None)

Creates a new TranslationFile instance from the given translation file(s).

file_path can be specified to initialize the file(s) right away. It takes the same arguments as TranslationFile.read().

Some translation files have an “include” tag which includes the translation strings of another translation file automatically. By default that behaviour is ignored and a warning is raised. To enable the automatic include, specify either of the base_dir or parent variables.

Note

the inclusion paths for other translation files are relative to root of the content.ggpk and if using a file system it is expected to mirror this behaviour

Parameters:

• file_path (Iterable or str or None) – The file to read. Can also accept an iterable of files to read which will all be merged into one file. Also see read()
• base_dir (str or None) – Base directory from where other translation files that contain the “include” tag will be included
• parent (TranslationFileCache or None) – parent TranslationFileCache that will be used for inclusion

Raises:

• ValueError – if both parent and base_dir are specified
• TypeError – if parent is not a TranslationFileCache

copy()

Creates a shallow copy of this TranslationFile.

Note that the same objects will still be referenced.

Returns:copy of self Return type:TranslationFile

get_read_buffer(file_path_or_raw, function, *args, **kwargs)

Will attempt to open the given file_path_or_raw in read mode and pass the buffer to the specified function. The function must accept at least one keyword argument called ‘buffer’.

Parameters:

• file_path_or_raw (BytesIO | bytes | str) – file path, bytes or buffer to read from
• args – Additional positional arguments to pass to the specified function
• kwargs – Additional keyword arguments to pass to the specified function

Returns:

Result of the function

Return type:

object

Raises:

TypeError – if file_path_or_raw has an invalid type

get_translation(tags, values, lang='English', full_result=False, use_placeholder=False, only_values=False)

Attempts to retrieve a translation from the loaded translation file for the specified language with the given tags and values.

Generally the list of values should be the size of the number of tags.

If instead of the real value a placeholder is desired use_placeholder can be used.

Parameters:

• tags (list[str]) – A list of identifiers for the tags
• values (list[int] or list[int, int]) – A list of integer values to use for the translations. It is also possible to use a list of size 2 for each element, which then will be treated as range of acceptable value and formatted accordingly (i.e. (x to y) instead of just x).
• lang (str) – Language to use. If it doesn’t exist, English will be used as fallback.
• full_result (bool) – If true, a TranslationResult object will be returned
• use_placeholder (bool or callable) – If true, Instead of values in the translations a placeholder (i.e. x, y, z) will be used. Values are still required however to find the “correct” wording of the translation. If a callable is specified, it will call the function with the index as first parameter. The callable should return a string to use as placeholder.
• only_values (bool) – If true, only the handled values instead of the string are returned

Returns:

Returns a list of found translation strings. The list may be empty if none are found. If full_result is specified, a TranslationResult object is returned instead

Return type:

list[str] or TranslationResult

merge(other)

Merges the current translation file with another translation file.

Parameters:other (TranslationFile) – other TranslationFile object to merge with Returns: Return type:None

read(file_path_or_raw, *args, **kwargs)

Reads the file contents into the specified path or buffer. This will also reset any existing contents of the file.

If a buffer or bytes was given, the data will be read from the buffer or bytes object.

If a file path was given, the resulting data will be read from the specified file.

Parameters:

• file_path_or_raw (BytesIO | bytes | str) – file path, bytes or buffer to read from
• args – Additional positional arguments
• kwargs – Additional keyword arguments

Returns:

result of the read operation, if any

Return type:

object

Raises:

TypeError – if file_path_or_raw has an invalid type

reverse_translation(string, lang='English')

Attempt to reverse a translation string and return probable candidates as well as probable values the translation string was used with.

Warning

During translation there is a loss of information incurred and there are cases where it might be impossible reconstruct the string.

Warning

The method can only work of exact translation strings, so minor differences already might result in failure detection. As such strings from previous versions of Path of Exile may not work.

Parameters:

• string (str) – The translation string to reverse
• lang – The language the string is in

Returns:

TranslationReverseResult instance containing any found translation instances as well as the values.

Return type:

TranslationReverseResult

class PyPoE.poe.file.translations.TranslationFileCache(*args, merge_with_custom_file=None, **kwargs)

Bases: PyPoE.poe.file.shared.cache.AbstractFileCache

Creates a memory cache of TranslationFile objects.

It will store any loaded file in the cache and return it as needed. The advantage is that there is only one object that will handle all translation files and only load them if they’re not in the cache already.

In particular this is useful as many translation files include other files which will only be read once and then passed to the other file accordingly - separately loading those files would read any included file multiple times, as such there is a fairly significant performance improvement over using single files.

Variables:

• '_ggpk' (GGPKFile) –
• '_path' (str) –
• 'files' (dict[str, AbstractFileReadOnly]) – Dictionary of loaded file instances and their related path

FILE_TYPE

alias of TranslationFile

__getitem__(item)

Shortcut for TranslationFileCache.get_file() that will also added Metadata automatically.

That means the following is equivalent: obj[‘stat_descriptions.txt’] obj.get_file(‘Metadata/StatDescriptions/stat_descriptions.txt’)

Parameters:item (str) – file name/path relative to the Metadata/StatDescriptions/ directory Returns:the specified TranslationFile Return type:TranslationFile

__init__(*args, merge_with_custom_file=None, **kwargs)

Parameters:

• path_or_ggpk (str | GGPKFile) – The root path (i.e. relative to content.ggpk) where the files are stored or a PyPoE.poe.file.ggpk.GGPKFile instance
• files (Iterable) – Iterable of files that will be loaded right away
• files_shortcut (bool) – Whether to use the shortcut function, i.e. self.__getitem__
• instance_options (dict[str, object]) – options to pass to the file’s __init__ method
• read_options (dict[str, object]) – options to pass to the file instance’s read method
• merge_with_custom_file (None, bool or TranslationFile) – If this option is specified, each file will be merged with a custom translation file. If set to True, it will load the default translation file located in PyPoE’s data directory. Alternatively a TranslationFile instance can be passed which then will be used.

Raises:

• TypeError – if path_or_ggpk not specified or invalid type
• ValueError – if a PyPoE.poe.file.ggpk.GGPKFile was passed, but it was not parsed

get_file(file_name)

Returns the specified file from the cache (and loads it if not in the cache already).

Note that the file name must be relative to the root path of exile folder (or a virtual) folder or it won’t work properly. That means ‘Metadata/stat_descriptions.txt’ needs to be referenced as such. For a shortcut consider using obj[name] instead.

Parameters:file_name (str) – file name/path relative to the root path of exile directory Returns:the specified TranslationFile Return type:TranslationFile

path_or_ggpk

The path or PyPoE.poe.file.ggpk.GGPKFile instance the cache was created with

class PyPoE.poe.file.translations.TranslationResult(found, found_lines, lines, missing, missing_values, partial, values, unused, values_parsed, source_ids, source_values, extra_strings)

Bases: PyPoE.poe.file.translations.TranslationReprMixin

Translation result of TranslationFile:get_translation().

Variables:

• found (list[Translation]) – List of found Translation instances (in order)
• found_lines (list[str]:) – List of related translated strings (in order)L
• lines (list[str]) – List of translated strings (minus missing ones)
• missing_ids (list[str]) – List of missing identifier tags
• missing_values (list[int]) – List of missing identifier values
• partial (list[Translation]) – List of partial matches of translation tags (in order)
• values (list[int]) – List of values (in order)
• values_unused (list[int]) – List of unused values
• values_parsed (list[str]) – List of parsed values (i.e. with quantifier applied)
• source_ids (list[str]) – List of the original tags passed before the translation occurred
• source_values (list[int] or list[int, int]) – List of the original values passed before the translation occurred
• extra_strings (list[dict[str, str]]) – List of dictionary containing extra strings returned. The key is the quantifier id used and the value is the string returned.

found_ids

Generates a list of found ids and returns it.

Returns:List of found ids Return type:list[list[str]]

missing

Zips missing_ids and missing_values.

Returns: Return type:zip

class PyPoE.poe.file.translations.TranslationReverseResult(translations, values)

Bases: PyPoE.poe.file.translations.TranslationReprMixin

Result of TranslationFile.reverse_translation()

Variables:

• translations (list[Translation]) – List of Translation instances
• values (list[list[float]]) – List of values

PyPoE.poe.file.translations.get_custom_translation_file()

Returns the currently loaded custom translation file.

Loads the default file if none is loaded.

Returns:the currently loaded custom translation file Return type:TranslationFile

PyPoE.poe.file.translations.set_custom_translation_file(file=None)

Sets the custom translation file.

Parameters:file (str) – Path where the custom translation file is located. If None, the default file will be loaded

PyPoE.poe.file.translations.install_data_dependant_quantifiers(relational_reader)

Install data dependant quantifiers into this class.

Parameters:relational_reader (RelationalReader) – RelationalReader instance to read the required game data files from.

Internal API

API for internal use, but still may be useful to work with more directly.

class PyPoE.poe.file.translations.Translation

Bases: PyPoE.poe.file.translations.TranslationReprMixin

Representation of a single translation.

A translation has at least one id and at least the English language (along with the respective strings).

Variables:

• languages (list[TranslationLanguage]) – List of TranslationLanguage instances for this Translation
• ids (list[str]) – List of ids associated with this translation

__eq__(other)

Return self==value.

get_language(language='English')

Returns the TranslationLanguage record for the specified language.

As a fallback if the language is not found, the English TranslationLanguage record will be returned.

Parameters:language (str) – The language to get. Returns:Returns the TranslationLanguage record for the specified language or the English one if not found Return type:TranslationLanguage

class PyPoE.poe.file.translations.TranslationLanguage(language, parent)

Bases: PyPoE.poe.file.translations.TranslationReprMixin

Representation of a language in the translation file. Each language has one or multiple strings.

Variables:

• parent (Translation) – The parent Translation instance
• language (str) – the language of this instance
• strings (list[TranslationString]) – List of TranslationString instances for this language

__eq__(other)

Return self==value.

get_string(values, use_placeholder=False, only_values=False)

Formats the string according with the given values and returns the string and any left over (unused) values.

If use_placeholder is specified, the values will be replaced with a placeholder instead of the actual value.

If only_values is specified, the instead of the string the formatted values will be returned.

Parameters:

• values (list[int]) – A list of values to be used for substitution
• use_placeholder (bool or callable) – If true, Instead of values in the translations a placeholder (i.e. x, y, z) will be used. Values are still required however to find the “correct” wording of the translation. If a callable is specified, it will call the function with the index as first parameter. The callable should return a string to use as placeholder.
• only_values (bool) – Whether to return formatted values instead of the formatted string.

Returns:

Returns the formatted string. See TranslationString:format_string() for details.

Return type:

str or list[int], list[int], list[int], dict[str, str]

reverse_string(string)

Attempts to find a match for the given string and returns a list of reversed values if a match is found for this language.

Parameters:string (str) – String to match against Returns:handled list of values or None if not found Return type:None or list

class PyPoE.poe.file.translations.TranslationString(parent)

Bases: PyPoE.poe.file.translations.TranslationReprMixin

Representation of a single translation string. Each string comes with it’s own quantifiers and acceptable range.

Variables:

• parent (TranslationLanguage) – parent TranslationLanguage instance
• quantifier (TranslationQuantifierHandler) – the associated TranslationQuantifierHandler instance for this translation string
• range (list[TranslationRange]) – list of TranslationRange instances containing the acceptable ranges for this translation as a list of instances for each index
• strings (list[str]) – translation string broken down into segments
• tags (list[int]) – tags for value replacement between segments
• tags_types (list[str]) – list of tag types

__eq__(other)

Return self==value.

as_format_string

The translation string as python str.format string

Returns:str.format string Return type:str

format_string(values, is_range, use_placeholder=False, only_values=False)

Formats the string for the given values.

Optionally use_placeholder can be specified to return a string formatted with a placeholder in place of the real value. It will use lowercase ASCII starting at x. For indexes > 3, it will use uppercase ASCII.

If only_values is specified, no string formatting will performed and instead just parsed values will be returned.

Parameters:

• values (list[int]) – List of values to use for the formatting
• is_range (list[bool]) – List of bools representing whether the values at the list index is a range or not
• use_placeholder (bool or callable) – If true, Instead of values in the translations a placeholder (i.e. x, y, z) will be used. Values are still required however to find the “correct” wording of the translation. If a callable is specified, it will call the function with the index as first parameter. The callable should return a string to use as placeholder.
• only_values (bool) – Only return the values and not

Returns:

Returns 4 values.

The first return value is the formatted string. If only placeholder is specified, instead of the string a list of parsed values is returned.

The second return value is a list of unused values.

The third return value is a list of used values.

The forth return value is a dictionary of extra strings

Return type:

str or list[int], list[int], list[int], dict[str, str]

match_range(values)

Returns the accumulative range rating of the specified values.

Parameters:values (list[int] or list[float]) – List of values Returns:Sum of the ratings Return type:int

reverse_string(string)

Attempts to match this TranslationString against the given string.

If a match is found, it will attempt to cast and reverse all values found in the string itself.

For missing values, it will try to insert the range maximum/minimum values if set, otherwise None.

Parameters:string (str) – string to match against Returns:handled list of values or None if no match Return type:list[int] or None

string

Reconstructed original string that would be used for translation

Returns:the original string Return type:str

class PyPoE.poe.file.translations.TranslationRange(min, max, parent)

Bases: PyPoE.poe.file.translations.TranslationReprMixin

Object to represent the acceptable range of a translation.

Many translation strings only apply to a given minimum or maximum number. In some cases there are also special strings for specific conditions.

For example, 100 for freeze turns into “Always Freeze” whereas less is “chance to freeze”.

Variables:

• parent (TranslationString) – parent TranslationString instance
• min (int) – minimum range
• max (int) – maximum range

__eq__(other)

Return self==value.

in_range(value)

Checks whether the value is in range and returns the rating/accuracy of the check performed.

Parameters:value (int) – Value to check Returns:Returns the rating of the value -100 if mismatch (out of range) 0 if no match 1 if any range is accepted 2 if either minimum or maximum is specified 3 if both minimum and maximum is specified Return type:int

class PyPoE.poe.file.translations.TranslationQuantifierHandler

Bases: PyPoE.poe.file.translations.TranslationReprMixin

Class to represent and handle translation quantifiers.

In the GGG files often there are qualifiers specified to adjust the output of the values; for example, a value might be negated (i.e so that it would show “5% reduced Damage” instead of “-5% reduced Damage”).

Variables:

• index_handlers (dict[str, list[int]]) – Mapping of the name of registered handlers to the ids they apply to
• handlers (dict[str, TranslationQuantifier]) – Class variable. Installed handlers
• reverse_handlers (dict[str, TranslationQuantifier]) – Class variable. Installed reverse handlers.

__eq__(other)

Return self==value.

handle(values, is_range)

Handle the given values based on the registered quantifiers.

Parameters:

• values (list[int]) – list of values
• is_range (Iterable of bools) – specifies whether the value at the index is a range or not. Must be the same length as values.

Returns:

handled list of values

Return type:

list[int]

handle_reverse(values)

Reverses the quantifier for the given values.

Parameters:values (list[int]) – list of values Returns:handled list of values Return type:list[int]

classmethod install_quantifier(quantifier)

Install the specified quantifier into the generic quantifier handling

Parameters:- TranslationQuantifier (quantifier) – TranslationQuantifier instance

register_from_string(string)

Registers handlers from the quantifier string.

Parameters:

• string (str) – quantifier string
• offset (int) – offset this operation is appearing at (to show errors)

Warning Classes

class PyPoE.poe.file.translations.TranslationWarning

Bases: PyPoE.poe.file.shared.ParserWarning

__init__

Initialize self. See help(type(self)) for accurate signature.

with_traceback()

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

class PyPoE.poe.file.translations.MissingIdentifierWarning

Bases: PyPoE.poe.file.translations.TranslationWarning

__init__

Initialize self. See help(type(self)) for accurate signature.

with_traceback()

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

class PyPoE.poe.file.translations.UnknownIdentifierWarning

Bases: PyPoE.poe.file.translations.TranslationWarning

__init__

Initialize self. See help(type(self)) for accurate signature.

with_traceback()

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

class PyPoE.poe.file.translations.DuplicateIdentifierWarning

Bases: PyPoE.poe.file.translations.TranslationWarning

__init__

Initialize self. See help(type(self)) for accurate signature.

with_traceback()

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