I18n-sync is a simple node JS project that provides a restful api for syncing translations, and their locations to the cloud. All work is done via restful api calls in order to update files and configurations. All source code is available here.
Supported Providers
At the moment i18n-sync caters for
- AWS S3
- Google Cloud Storage
- Digital Ocean Spaces
Future deployments will cater for Azure and other providers, and also for a filesystem based solution.
Why does this exist?
Companies may have a hard time with translations. Managing multiple projects, repos and translations means more work than is actually required just to get the right translations into place. With this you will be able to store your projects translations on the cloud and have them easily accessible for all.
This project also means that you won’t be encountering anymore merging errors with your translations files, if two people publish at the same time then the endpoint is called twice to update the file twice. This will avoid any race conditions and the possibility of lost work.
Security
The i18n-sync must have read / write access to the CDN / bucket that is storing your translations. It exposes a web server that allows for modifying the state of your production application. It is password protected with HTTP basic authentication.
The following security constraints are highly recommended to secure the i18n-sync.
The i18n-sync’s web server is only exposed within your VPC. Your CI runners should either be within the VPC or tunnel into it when calling the i18n-sync. The i18n-sync has HTTP basic authentication enabled, and only the CI runners know the username and password.
Example Usage
This github repo shows an example on how to use this project within your organisation.
Installation and usage
i18n-sync is available on docker hub [ thewebuiguy/i18n-sync ] the image expects you to have a
config.jsoni18n-sync is available as an npm package
npm install i18n-cloud-syncor run it directly via
npx i18n-cloud-sync config.jsonConfiguration File
i18n-sync expects a config.json file to be present in the application, this will allow you to password protect your projects in which you must provide a username and password. Here are a list of properties you must provide for this project to be able to work.
region - the region of aws that you are using if you are using aws.locations - this is an object of key value pairs which shows where your different translation files live.username - (OPTIONAL) the username that will be used by your CI in order to login via basic authpassword - (OPTIONAL) the password that needs to be used by your CI in order to login via basic auths3Endpoint - (OPTIONAL) used for digital ocean spaces and also for awsport - (OPTIONAL) allows you to spin the project up on another port.Config File ExampleOption 1 JSON File
{
"username": "username",
"password": "password",
"region": "eu-west-1",
"s3Endpoint": "http://mycdn.com",
"locations": {
"moduleOneEn": "s3://mycdn.com/en.json",
"moduleOneDe": "s3://mycdn.com/de.json"
}
}module.exports = {
"username": process.env.HTTP_USERNAME,
"password": process.env.HTTP_PASSWORD,
"region": "eu-west-1",
"s3Endpoint": "http://mycdn.com",
"locations": {
"moduleOneEn": "s3://mycdn.com/en.json",
"moduleOneDe": "s3://mycdn.com/de.json"
}
}** Note in order to do this you must change the start command in your docker file e.g.
CMD ["yarn", "start", "config.json"]Supported Provider Examples
If your translations files file is hosted by AWS S3, you can use this project to modify the s by specifying in your config s3:// in the locations config object.
The format of the string is
s3://bucket-name/file-name.jsoni18n-sync relies on the AWS_DEFAULT_REGION environment variables for authentication with S3.
config.json:
{
"region": "eu-west-1",
"s3Endpoint": "https://mycdn.com",
"locations": {
"moduleOneEn": "s3://mycdn.com/en.json",
"moduleOneDe": "s3://mycdn.com/de.json"
}
}If your translations files are hosted on Digital Ocean Spaces, you can use the api to modify translations files by specifying in your config spaces:// in the locations config object.
The format of the string is
spaces://bucket-name.digital-ocean-domain-stuff.com/file-name.jsonSince the API Digital Ocean Spaces is compatible with the AWS S3 API, i18n-sync uses aws-sdk to communicate with Digital Ocean Spaces. As such, all options that can be passed for AWS S3 also are applied to Digital Ocean Spaces. You need to provide AWS CLI environment variables for authentication with Digital Ocean Spaces, since i18n-sync is using aws-sdk to communicate with Digital Ocean.
Instead of an AWS region, you should provide an s3Endpoint config value that points to a Digital Ocean region.
config.json:
{
"s3Endpoint": "https://nyc3.digitaloceanspaces.com",
"locations": {
"moduleOneEn": "spaces://mycdn.com/en.json",
"moduleOneDe": "spaces://mycdn.com/de.json"
}
}Note that you must have the
GOOGLE_APPLICATION_CREDENTIALSconfig.json:
{
"locations": {
"moduleOneEn": "google://bucketname/en.json"
}
}Endpoints
GET /healthwill run a health check to see the server is running
GET /locationswill return an overview of available locations
curl -i localhost:3000/locationsGET /<location>will return the assets available at that location
curl -i localhost:3000/moduleOneEn -> {... some translations}POST /update/<location>must includes a translations object in the bodywill update the given location with data passed into it via the request body
curl -d { "translations": { "key": "translation" } } -X POST localhost:3000/update/moduleOneEnPUT /update-config-locationswill update configuration locations in your config file
curl -d { "key": "moduleTwoEn", "value":"s3://mycdn.com/moduleTwoEn.json" } -X PUT localhost:3000/update-config-locationsDELETE delete-config-location/<location>not to be used very often only when removing or deprecating old translations
curl -X DELETE localhost:3000/delete-config-location/moduleOneEnIf username or password are set in your config these must be passed via basic auth.
**using httpie
http -a username:password :3000/locations