Manipulating files on disk via Loco Translate

Unlike your blog posts which live in the database, WordPress reads translations from regular files on your server's disk. For this reason, creating updating and deleting translation files requires that Loco Translate can "write to disk" via the webserver.

There are two ways you can write to disk in Loco Translate: Directly or remotely.

1. Direct filesystem access

Loco Translate will always write to disk directly if it can. This means manipulating files via PHP in exactly the same way that other parts of WordPress do. If PHP doesn't have permission, you will be warned via the Loco user interface.

There is a lot of information available on WordPress file permissions and we won't repeat it all here. We recommend you read WordPress's own article on changing file permissions and take note of the security risks.

Briefly, these are the write operations that Loco needs to perform when updating translation files:

• Creation
  If a file doesn't exist Loco will have to create it. This means write permission on the containing directory is required.

• Modification
  When overwriting an existing file, Loco needs permission to write to the file itself. Note that with backups enabled Loco will also need to create new files in order to save revisions.

• Deletion
  Loco will never delete files unless you ask it to, with the exception of pruning old backups. Deleting files requires the same directory permissions as creation, because you're modifying the contents of a directory, not a file.

Please don't ask us what file permissions you need or how to set them. The exact permissions you need will depend on many factors beyond our knowledge and possibly beyond your control. Furthermore, we cannot get involved in the security of your server. If you're struggling with file permissions please ask your IT department or hosting provider for help.

2. Remote filesystem access

If direct filesystem access is not available for a particular write operation, Loco will prompt you to enter remote file system credentials (FTP, SFTP or SSH). This works in exactly the same was as WordPress's own plugin and theme installation process. You may have seen this screen before when running updates or installing new components:

You will have to enter these details every time Loco needs them, unless you either save them in your WordPress config, or hold them temporarily in Loco's own session persistence option. Note that we don't recommend saving your credentials at all if you can avoid it, and we don't recommend submitting passwords over the web unless your site is secured with SSL.

The remote connection feature is designed for users that already have file system credentials set up for WordPress background updates. We don't recommend using this approach unless you've taken measures to ensure its security.

Please don't ask us to help you with your remote server access. Only use these features if you understand the security risks and possess the required access credentials. If you have any doubts, please ask your hosting provider for advice.

Security and best practice

You may be wondering which of the above methods is the most secure. The answer is that they can both be insecure in different ways, depending on how your server and your WordPress are set up. If you're not an expert in server security, ask your web hosting provider for advice on the most secure way to provide write access to where your translation files are located.

The bottom line is that you do not need to have a writeable file system in order to simply display translations - only to update them. The most secure way to run Loco Translate is on a private development server. Then simply upload read-only MO files to sites that need them.

Installed files & WordPress updates

Whichever method you use to modify files, be aware that some files can also be modified by WordPress updates. Understanding this is critical to ensuring your translations aren't deleted without your knowledge. This is especially important if you have auto-updates enabled.

DO NOT edit translation files that are already installed

The recommended approach is to override translations in your own custom files. These should be saved in a safe location where they won't be deleted by WordPress.

• See: Choosing a location to save your files
• FAQ: Why have my translations been deleted?
• Guide: How to customize existing translations

Loco Translate considers any part of the file system that WordPress can modify during updates as "installed" even if you saved the file there yourself. Note that this doesn't just apply to theme and plugin directories. All the following paths are considered "unsafe" for saving anything you want to keep.

• wp-content/themes
• wp-content/plugins
• wp-content/languages †
• wp-content/languages/themes
• wp-content/languages/plugins

† Other subdirectories of the languages folder are safe. You will notice that Loco's custom folder is at wp-content/languages/loco.

The plugin settings have options to control how Loco Translate protects these locations. If you know what you're doing you might want to disable the warnings, but if you want to be extra careful you can block write operations to any of these locations.

Disallowed file modifications

You may see the message "File modification is disallowed by your WordPress config”. This means your WordPress site has explicitly blocked write access to a particular file. This is probably deliberate so we recommend discussing the issue with your hosting provider before attempting to circumvent their security measures.

Loco Translate honours the result returned from the wp_is_file_mod_allowed WordPress function. This in turn honours the DISALLOW_FILE_MODS configuration, but your situation may be more complex. We can't provide specific advice on how your site is set up.

You may be able to modify this behaviour using the file_mod_allowed WordPress filter, but proceed with extreme caution as you may cause bigger problems by lifting important file protections.

A better solution may be to alter the context of the file update to make an exception. Loco Translate calls wp_is_file_mod_allowed with the same context that WordPress does when it attempts to update an installed translation file ("download_language_pack"). That context can be modified with the filter loco_file_mod_allowed_context.