Gathering Assets
Asset gathering is the part of the localization pipeline that uses the most resources. This is because localization often must load Assets (and their dependencies) to extract the localizable text values contained within them. In order to minimize the number of Assets that actually need to be loaded during a gather, Unreal Engine (UE) adds a "gather cache" to the header of Asset files (generated when you save), which means that only the Asset header needs to be loaded in order to gather the text.
You can view the current cache for an Asset by going to the Asset Localization menu in the Content Browser, and selecting Show Localization Cache.
Certain kinds of Assets (such as Blueprints, or Levels with a non-empty Level Blueprint) are unable to generate a gather cache due to their use of bytecode. This is because UE gathers text values from bytecode, but bytecode is too volatile to be reliably cached on save.
A summary of how many Assets are uncached due to bytecode is printed to the log during an Asset gather. If you find your Asset gather is spending most of its time gathering from Assets that contain bytecode, then you might consider moving the text within those Assets into String Tables so that you can refer to those entries instead.
Only Assets that contain a serialized text value that passes FText::ShouldGatherForLocalization are loaded during an Asset gather. Culture-invariant, empty, and whitespace-only text, as well as String Table references, all fail this check. This is why using a String Table can improve your Asset gather performance.
Validating Asset Caches
There are some utilities available to help report or fix stale and missing gather caches on Assets in your project. These take a while to run, because they have to load every Asset into memory. However, they can offer significant future savings if you have a large number of uncached Assets. These utilities are run as extra arguments in the normal localization commandlet.
Example:
-run=GatherText-config=Config/Localization/Game_Gather.ini
-ReportStaleGatherCache
If you are upgrading a project from an Unreal Engine version older than 4.20, you should at least run ReportStaleGatherCache to verify that your cache is up-to-date, since stale caches can cause localization issues.
These options are not exposed in the Localization Dashboard. Instead you must use the gather INI file generated by the dashboard for your localization target, and run the localization commandlet manually.
| Argument | Description |
|---|---|
ReportStaleGatherCache |
Generates a StaleGatherCacheReport.txt file alongside the manifest for your localization target. This file contains a list of any Assets that contain a stale gather cache. |
FixStaleGatherCache |
Attempts to automatically fix any Assets that contain a stale gather cache, by re-saving them. |
FixMissingGatherCache |
For Assets too old to have a gather cache, this attempts to automatically fix Assets that are missing a gather cache by re-saving them. |