The Sync function

Updating files with available source strings

Loco Translate provides a Sync button from within the file editor. The purpose of this function is to fetch the translatable source strings that are currently available and update the file accordingly.

There are broadly two versions of this:

Updating translation files from their template (merging).
Updating template files from the source code (extracting).

If you are not familiar with these concepts, please read Working with POT files.

Updating translation files

To sync a PO file via WordPress admin, open it in the editor and press the Sync button in the tool bar. This process fetches the currently available source strings and applies them to the existing PO file. This may result in new strings being added and old strings being removed.

New strings (not previously in the file) are added and will appear untranslated.
Strings in the file that are no longer defined in the template may be dropped.
Strings which have changed only slightly may be marked as fuzzy. See below.

You will see a short summary of this once the editor is updated, but nothing is yet saved to disk. If you are happy with the changes, click Save. If something looks wrong, don't save the file. The first thing you should do is open the template file and check it is correct and up to date. If it doesn't reflect what you think should be translatable then contact whoever provided it.

If you are syncing with another PO file instead of a provided template, then open that file first and ensure it's up to date. There's no point syncing to a file that is not in sync.

If there is no template and you haven't defined one, see the next section.

Extracting strings

Generally this function is aimed at theme and plugin developers. We recommend against translators and site owners generating their own templates. It is safer to use Loco Translate's Copy function instead. See FAQ How can I add a language without a translation template?

To update a POT (template) file via WordPress admin, click "Edit template" to view it in the file editor and press the Sync button in the tool bar. This process fetches the latest source strings from the bundle's PHP files and populates the editor.

Translatable strings in the file that are no longer in the source code are dropped.
New translatable strings (not previously in the file) are added.

You will see a short summary of this once the editor is updated, but nothing is yet saved to disk. If you are happy with the changes, click Save. If you are not happy with the changes, you may have a problem with the bundle's configuration. This is an advanced topic. See String extraction for more detail.

Keeping files in sync

Sync operations must be done manually whenever you update your WordPress, because any number of themes and plugins may have changed their available source strings.

Loco Translate deliberately avoids running these sync operations automatically. It may seem laborious to sync everything manually, but it is preferable to losing translations. Many things can go wrong and Loco Translate cannot guarantee that all your plugins and themes have correct and up to date files. Doing this behind your back will likely produce mysterious errors and you'll have no idea why.

As of version 2.4.5 Loco Translate provides two WP-CLI commands for extracting strings and syncing translations. These commands can sync all your bundles at once, but use them with care as they don't make the process any less prone to error. We recommend you always back up your site before performing any upgrade, including running operations like this.

Fuzzy matching

Fuzzy matching is performed during Sync for any strings that are currently translated, but for which the source string is redundant.

If a source text has changed only slightly, it may be possible to say that a new string being added is a modification of an old string being removed. In this case its translation will kept in the file and marked as Fuzzy. This tells translators that it should be reviewed in light of the updated source.

As of version 2.4.5 you can adjust the tolerance for fuzzy matching in the plugin settings. This is entered as a percentage value (0-100) where zero disables fuzzy matching completely. As a general guide: Low numbers mean more redundant translations will be dropped; Larger numbers mean more will be kept, but they may make less sense.

Fuzzy matching was added in version 2.4.0, but changed considerably in 2.4.5. For anyone interested in the technical details, Loco Translate now uses Levenshtein distance to compare all the old strings (that would be dropped) with all the new strings (that would be added). The most similar matches within your configured threshold are then used to prevent the translations from being removed.

Some notes on the current implementation:

Comparison is done case-insensitively so that "Foo" is seen as more similar to "FOO" than to "Foot".
Distance scores are employed relatively to the length of strings. For example "bar" compared to "baz" is one third different, so you'd need a tolerance setting of at least 34% for the pair to be considered as a potential match.
PHP's Levenshtein implementation is not multi-byte safe, so there are potential issues here. For example "a" is closer to "b" than to "á". However as WordPress source strings should be English this may be a non-issue.
Distance calculations include HTML code differences, but this could cause problems. For example"<b>Foo</b>" is closer to "<b>Bar</b>" than to "Foo", despite that the translation for the latter would be more correct.

The algorithm is quite likely to change and improve, and we are open to feedback on how effective you find it.