Automatically publishing translation files to remote systems

This feature is currently in Beta. We welcome your feedback.

Automatic deployment comprises two parts: (1) Configuring a host, and (2) defining a deployment to publish.

1. The host is generally a remote service (e.g. a CDN, or file repository) which you configure and store in Loco along with its access credentials. Host configurations can be used for multiple deployments if needed, and can be shared with other team members.

2. The deployment itself is the collection of files you publish to a host. Each collection is defined as per the Export API parameters: Choose your file format, and filter the exportable translations according to tags, status, etc..

Adding a host

• Open the developer tools modal from any project view where you see the :wrench icon:
• Switch to the "Deployments" tab, and click the "New host" link

Choose from one of the following providers:

• Loco CDN - A public CDN with an open CORS policy, included in your plan.
• Amazon S3 - Can be used as an origin server for files on your own domain.
• GitHub - Commit translation changes directly to a Git repository.

AWS and Github integrations are supported on a "bring your own key" basis. See the linked pages for information on each provider. What follows is general information for deploying to any host.

Publishing files

Once you've added a host you can publish translation files to it. This is done by defining one or more deployments. Each deployment is a set of files you want to publish automatically when your project is updated. You can also publish them "manually" (on demand).

The interface for selecting what files to publish is very similar to Loco's file export dialogue. The options include everything that the Export API supports, plus a destination path which controls how and where each locale is exported on the target host.

Frequency

This restricts how often (at most) your files will be deployed. A daily or hourly schedule will publish your files no more often than once per day, or once per hour, and if no changes are detected then nothing will be deployed.

The most frequent (continuous) will still only be every minute or so (if there are changes). If you need such rapid updates to reflect on your servers, this method is preferable to continually exporting files via the API which can exceed rate limits.

If you only want to publish your files manually, set the frequency to "Paused", and run the deployment as needed from the UI.

See: general help with task scheduling.

Destination path

The destination path dictates where (under your host root) the files will be deployed. It also controls how multiple locales are expanded to multiple export paths. The following examples cover most use cases:

• Leaving blank:
  The default is to export each locale in the project to a separate file named with the locale code. e.g. For a pair of English and German JSON files: Loco will export en.json and de.json to the root of the target host.

• Directory path:
  If you enter path/to/langs Loco will export path/to/langs/en.json and path/to/langs/de.json. The default file name is simply appended to your directory path.

• Custom path template:
  Loco uses a path template to expand multiple locales to multiple files. The default is {locale}.{ext}, but you can override it. e.g. lang/{locale}/foo.{ext} would export lang/en/foo.json and lang/de/foo.json.

  If you have specific naming requirements for your platform, use this option with a locale alias. This can be any string, e.g. {locale|alias:foo}.{ext}.

• Single file export:
  Formats that support multiple locales can be coerced to a single file by entering a name without a locale placeholder. e.g. path/to/file.csv or file.{ext}. The latter will ensure the correct extension is used as per your selected format.

• Archives:
  All formats can be deployed as an archive by entering a compressed file extension (zip, tar or tgz), e.g. path/to/all.zip.

Note that literal file extensions (other than compressed archives) are NOT checked, and don't change the behaviour of your selected file format. For example you could select JSON and export it to .jsonp or .js, but it would still be plain old JSON.

Custom parameters

If you're familiar with the Export API, you may already be using additional parameters to download your project files. You can add any legal API parameter here.

Permanence

With the exception of our own CDN, file deployments to remote hosts are one-way. Loco never deletes, or moves any files it has previously published. If you need to remove files from a target host, you must do so via your own access to the destination.

Sharing hosts

It's convenient that other team members can publish files to your hosts, but be sure that they're trusted to do so.

Only team members with Developer privileges can access deployment tools, which limits the scope of sharing. However, consider the risk of multiple developers pushing files to the same host.

For all remote services requiring access credentials - see our general advice on key security.

File collisions

Loco won't allow you to publish the same file path from multiple sources. This is a safety mechanism to avoid accidental file collisions.

For example: exporting foo.json to the root of a Git repository could easily be done from multiple projects, or by multiple people. It could also be done for different JSON schemas, or with different export options. All such scenarios would almost certainly produce unwanted results.

It's recommended to configure a useful destination path for each deployment to ensure that each set of published files is unique and clearly separated. If you see a file collision error, check your destination path is not ambiguous.