Callbacks

Callbacks are the way plugins communicate with Serge engine and modify or extend the behavior of localization cycle. Each plugin can listen to any number of callbacks. Some plugins have a predefined set of callbacks they listen to; others can be configured via configuration files. Documentation on each callback plugin shipped with Serge provides information on which callback phases are optional, and which are always on.

In the list below, callbacks are sorted by their first occurrence in the localization cycle.

before_job

Input parameters: none.

Return value: none.

This callback is called after the job is initialized and before the actual processing starts; phase can be used to implement some data initialization.

before_update_database_from_source_files

Input parameters: none.

Return value: none.

This callback is called immediately after before_job callback, before source files are scanned and parsed, and can be used to implement second phase of data initialization.

rewrite_path

Input parameters: (STRING)relative_file_path.

Return value: new value of (STRING)relative_file_path.

When source files are scanned, file path (relative to the root directory, see job → source_dir parameter) for files that match the file masks defined in a job is passed through rewrite_path callbacks. Each callback should either return an unmodified file path, or a rewritten one. Use this phase to change file names and paths, for example, remove language-specific filename suffixes. The final relative file path will be used for the corrensponding translation files, so rewriting the path affects the resulting translation folder/file structure.

after_load_file

Input parameters: (STRING)relative_file_path, (STRING)source_language, (STRINGREF)content.

Return value: none.

This callback is called every time a source file is loaded, which happens twice during localization cycle: when all source files are loaded to extract strings from, and when they are loaded as templates to generate localized files.

after_load_source_file_for_processing

Input parameters: (STRING)relative_file_path, (STRINGREF)content.

Return value: none.

This callback is called when a source file is loaded to extract strings from.

is_file_orphaned

Input parameters: (STRING)relative_file_path.

Return value: 1 if the file should be considered orphaned (and skipped), 0 otherwise.

This callback is called immediately after after_load_source_file_for_processing callback, and is used to filter out unwanted files (such files are marked as orphaned in the database).

can_process_source_file

Input parameters: (STRING)relative_file_path, (STRINGREF)content.

Return value: 1 if the file should be temporarily skipped, 0 otherwise.

This callback is called immediately after is_file_orphaned callback, and is used to temporarily skip files from being processed (such files are not marked as orphaned in the database).

rewrite_source

Input parameters: (STRING)relative_file_path, (STRING, OPTIONAL)language, (STRINGREF)source_string, (STRINGREF)hint.

Return value: none.

This callback is used to rewrite source string before it is passed through translation pipeline. It can be used to normalize string input, adjust punctuation, etc. Note that this rewriting happens before the can_extract phase, so it is run for all strings, even for ones that may later be discarded.

can_extract

Input parameters: (STRING)relative_file_path, (STRING, OPTIONAL)language, (STRINGREF)source_string, (STRINGREF)hint, (STRING)context, (STRING)key.

Return value: 1 if the string should be extracted for translation, 0 otherwise.

This callback is called in source file parsing cycle for each found string, and allows to skip certain strings from translation. Since each source file is parsed twice during localziation cycle, this callback will also be called twice for each extracted string. During the first pass, the language parameter is not set (since Serge is dealing with the source file); During the second pass, language is set to the target language this file is being generated for.

before_update_database_from_ts_file

DEPRECATED. Use before_update_database_from_ts_files.

before_update_database_from_ts_files

Input parameters: none.

Return value: none.

This callback is called after source files are scanned and parsed and before translation files are scanned and parsed.

before_update_database_from_ts_lang_file

Input parameters: (STRING)namespace, (STRING)relative_file_path, (STRING)language.

Return value: none.

This callback is called before each translation file is read.

can_process_ts_file

Input parameters: (STRING)relative_file_path, (STRING)language.

Return value: 1 if the translation file should be processed, 0 otherwise.

This callback is called immediately after before_update_database_from_ts_lang_file callback, and is used to skip translation files from being parsed.

rewrite_parsed_ts_file_item

Input parameters: (STRING)relative_file_path, (STRING)language, (STRINGREF)source_string, (ARRAYREF)flags, (STRINGREF)translation, (STRINGREF)comment, (BOOLEANREF)fuzzy, (STRINGREF)comment.

This callback is called in translation file parsing cycle for each unit, and allows to rewrite certain unit properties before it is processed.

after_update_database_from_ts_lang_file

Input parameters: (STRING)namespace, (STRING)relative_file_path, (STRING)language.

Return value: none.

This callback is called after each translation file is parsed and its translations have been imported.

before_generate_ts_files

Input parameters: none.

Return value: none.

This callback is called after translation files are scanned and parsed and before translation files are generated.

can_generate_ts_file

Input parameters: (STRING)relative_file_path, (STRING)language.

Return value: 1 if the translation file can be generated, 0 otherwise.

This callback is called before each translation file is about to be generated, and can be used to prohibit generating certain translation files.

can_translate

Input parameters: (STRING)relative_file_path, (STRING)language, (STRINGREF)source_string, (STRINGREF)hint.

Return value: 1 if the string can be translated (and thus, published in the translation file), 0 otherwise.

This callback is called for each string about to be added to translation file, and can be used to prohibit exposing certain strings for translation. The same callback is called when the localized files are generated.

add_dev_comment

Input parameters: (STRING)relative_file_path, (STRING)language, (STRINGREF)source_string, (ARRAYREF)dev_comments.

Return value: none.

This callback is called for units that are about to be added to the translation file, and is supposed to be used to add extra developer comments to the end of the provided array.

get_translation_pre

Input parameters: (STRING)source_string, (STRING)context, (STRING)namespace, (STRING)relative_file_path, (STRING)language, (BOOLEAN)disallow_similar_lang, (INTEGER)item_id, (STRING)key.

Return values (array): (STRING)translation, (BOOLEAN)fuzzy, (STRING)comment, (BOOLEAN)need_save.

This callback is called whenever Serge wants to get a translation for the string, before it tries looking up the translation in the database. If a plugin can't provide a translation, it should return both translation and comment member of the array as undefined values. If the comment is set but translation isn't, it means a valid 'empty' translation.

Plugin needs to provide true value for need_save flag for translation to be saved to the database. By default the translation won't be saved, and this makes sense when providing test auto-generated translations, which can always be generated on demand and which don't need to be stored in the database.

This callback is requested twice per localization cycle for each string: when generating translation files, and when generating localized files.

get_translation

This callback is identical to get_translation_pre callback, but is run after Serge has tried all its internal methods to get a translation, and failed. In other words, this callback is called to only for strings with missing translations.

This callback is requested twice per localization cycle for each string: when generating translation files, and when generating localized files. However, if the callback provides a translation at translation file generation step and this translation is saved into the database, callback won't be called again for the same string when localized files are being generated, since the translation will be already in the database.

before_generate_localized_files

Input parameters: none.

Return value: none.

This callback is called after the translation files have been generated and before generation of localized files has been started.

can_generate_localized_file

Input parameters: (STRING)relative_file_path, (STRING)language.

Return value: 1 if the localized file can be generated, 0 otherwise.

This callback is called before generating each localized file, and can be used to skip certain files. Note that it is called before the file was read from disk. If you need to analyze file content, use >This callback is similar to can_generate_localized_file_source callback instead.

rewrite_relative_output_file_path

Input parameters: (STRING)relative_file_path.

Return value: new value of (STRING)relative_file_path.

This callback is called before the localized file is about to be generated and is used to rewrite relative path (in other words, change output file location) before it expanded into an absolute path.

rewrite_absolute_output_file_path

Input parameters: (STRING)absolute_file_path.

Return value: new value of (STRING)absolute_file_path.

This callback is called to rewrite already expanded ouput file path.

can_generate_localized_file_source

Input parameters: (STRING)relative_file_path, (STRING)language, (STRINGREF)content.

Return value: 1 if the localized file can be generated, 0 otherwise.

This callback is similar to can_generate_localized_file callback, but it is called after the file has been read from disk, so that plugin can analyze source file contents to decide whether to skip the file or not.

after_load_source_file_for_generating

Input parameters: (STRING)relative_file_path, (STRING)language, (STRINGREF)content.

Return value: none.

This callback is called immediately after can_generate_localized_file_source callback for each file that was allowed to be generated.

rewrite_source

This is second time rewrite_source callback is called (when parsing source file to generate its localized copy).

can_extract

This is second time can_extract callback is called (when parsing source file to generate its localized copy).

can_translate

This is second time can_translate callback is called (when parsing source file to generate its localized copy).

get_translation_pre

This is second time get_translation_pre callback is called (when parsing source file to generate its localized copy).

get_translation

This is second time get_translation callback is called (when parsing source file to generate its localized copy).

rewrite_translation

Input parameters: (STRING)relative_file_path, (STRING)language, (STRINGREF)translation.

Return value: none.

This callback is used to rewrite translation before it is placed into a localized file. Note that this transformation is only applied to the translation in the localized file, and not in the translation file or database. This approach can be used to produce different set of localized files from the same set of translations. For example, one can statically rewrite product names, URLs or prices on the fly depending on language or some external parameters.

log_translation

Input parameters: (STRING)source_string, (STRING)context, (STRING)hint, (ARRAYREF)flags, (STRING)language, (STRING)key, (STRING)translation.

Return value: none.

This callback is called after the translation is determined for the source string, and can be used to save translations into a database, or save them in memory for some plugin-specific needs.

can_save_localized_file

Input parameters: (STRING)relative_file_path, (STRING)language, (STRINGREF)content.

Return value: 1 if the localized file can be saved to file, 0 otherwise.

This callback is called after the localized file content has been fully generated and is about to be saved to disk, and can be used to prevent saving certain files.

before_save_localized_file

Input parameters: (STRING)relative_file_path, (STRING)language, (STRINGREF)content.

Return value: none.

This callback is called immediately after can_save_localized_file callback for each file that was allowed to be saved to disk.

on_localized_file_change

Input parameters: (STRING)relative_file_path, (STRING)language, (STRINGREF)content.

Return value: none.

This callback is similar to before_save_localized_file callback, but it is called after the localized file was saved to disk, and only for files that were changed.

after_save_localized_file

Input parameters: (STRING)relative_file_path, (STRING)language, (STRINGREF)content.

Return value: none.

This callback is similar to before_save_localized_file callback, but it is called after the localized file was saved to disk, even if the generated file didn't change from its previous version.

after_job

Input parameters: none.

Return value: none.

This callback is called after the job finished execution; phase can be used to implement data cleanup or sending reports.