Callbacks are the way plugins communicate with Serge engine and modify or extend the behavior of its 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.
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.
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.
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 corresponding translation files, so rewriting the path affects the resulting translation folder/file structure.
Input parameters:
(STRING)absolute_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.
Input parameters:
(STRING)relative_file_path,
(STRINGREF)content.
Return value: none.
This callback is called when a source file is loaded into memory. This step can be used to unconditionally preprocess all the matching resource files on the fly, before the content hash of the file is calculated. See also the before_parsing_source_file callback below.
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).
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).
Input parameters:
(STRING)relative_file_path,
(STRINGREF)content.
Return value: none.
This callback is called after the file content was loaded, preprocessed, its hash value has been calculated, compared to a previous one stored in the database, and it was determined that the file content has been changed. This means that this callback (and content parsing that immediately follows it) will run only for files that have been modified since last run (or when Serge is running in a forced mode, which tells it to parse all the files unconditionally).
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.
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 localization 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.
DEPRECATED. Use 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.
Input parameters:
(STRING)relative_file_path,
(STRING)language.
Return value: new value of (STRING)relative_file_path, or undef if no rewrite is needed.
This callback is called before each translation file is read.
Input parameters:
(STRING)absolute_file_path,
(STRING)language.
Return value: new value of (STRING)absolute_file_path, or undef if no rewrite is needed.
This callback is called after rewrite_relative_ts_file_path, once the absolute path has been resolved.
Input parameters:
(STRING)namespace,
(STRING)relative_file_path,
(STRING)language.
Return value: none.
This callback is called after rewrite_absolute_ts_file_path, once the target file has been checked for presence.
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.
Input parameters:
(STRING)relative_file_path,
(STRINGREF)content.
Return value: none.
This callback is called once the translation interchange file is read into memory. The callback allows to preprocess the file's content before parsing.
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.
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.
Input parameters: none.
Return value: none.
This callback is called after translation files are scanned and parsed and before translation files are generated.
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.
This is second time rewrite_relative_ts_file_path callback is called (before generating the translation interchange file).
This is second time rewrite_absolute_ts_file_path callback is called (before generating the translation interchange file).
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.
DEPRECATED. Use add_hint.
Input parameters:
(STRING)source_string,
(STRING)context,
(STRING)namespace,
(STRING)relative_file_path,
(STRING)key,
(STRING)language,
(ARRAYREF)hint_lines.
Return value: none.
This callback is called for units that are about to be added to the translation file, and can change the hint_lines array, usually to append extra comments.
Input parameters:
(STRING)relative_file_path,
(STRINGREF)content.
Return value: none.
This callback is called once the translation interchange file content is generated in memory. The callback allows to post-process the file's content before saving.
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.
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.
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.
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.
Input parameters:
(STRING)relative_file_path.
Return value: new value of (STRING)relative_file_path, or undef if no rewrite is needed.
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.
Input parameters:
(STRING)absolute_file_path.
Return value: new value of (STRING)absolute_file_path, or undef if no rewrite is needed.
This callback is called to rewrite already expanded output file path.
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.
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.
This is second time rewrite_source callback is called (when parsing source file to generate its localized copy).
This is second time can_extract callback is called (when parsing source file to generate its localized copy).
This is second time can_translate callback is called (when parsing source file to generate its localized copy).
This is second time get_translation_pre callback is called (when parsing source file to generate its localized copy).
This is second time get_translation callback is called (when parsing source file to generate its localized copy).
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.
Input parameters:
(STRING)source_string,
(STRING)context,
(STRING)hint,
(ARRAYREF)flags,
(STRING)language,
(STRING)key,
(STRING)translation,
(STRING)namespace,
(STRING)relative_file_path.
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.
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.
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.
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.
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.
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.