G-i18n introduction
Many projects have to add support of i18n (internationalization) at some stage. There are multiple ways how engineers manage translations from implementation point of view and in most of the case it's quite complicated setup and process as such.
Core concept
The G-i18n project proposes simple-to-set-up and easy-to-use approach to address the i18n need for any type of project - e.g web application, mobile app or desktop program.
It bases its ideas on very well known GoogleSheets and REST API:
-
In GoogleSheet we keep translations as key-value pairs and may control access to this file for all collaborators (developers, translators, POs etc.) via embedded mechanisms of GoogleSheets - thus we don't have to spend any time on building UI to provide restricted access to tranlation lookups.
-
REST API gives access to those key-value pairs, taking responsibility for parsing your GoogleSheets, caching data, implementing some fallback solutions. This simplifies integration into any type of application.
Sample data
This proof of concept uses the following GoogleSheets document as the source: Translations POC.
Each tab represents a namespace (e.g. a page of the website), and expected to contain translations to different languages as columns in the following format:
Key | language-1 | language-2 | ... |
---|---|---|---|
label1.id | language-1 translation | language-2 translation | ... |
label2.id | language-1 translation | language-2 translation | ... |
For example:
ID | en-US | en-GB |
---|---|---|
color.gray | Color: gray | Colour: grey |
word.flavor | Flavor | Flavour |
word.analyze | Analyze | Analyse |
Getting Started
Prereqisites
- .NET 5.0 SDK to build the G-i18n tool (namely REST API)
- Google developer account to run the app against Google Sheets
- "docker" if you want to build a docker image and run it within docker container
Quick Start
In order to run the G-i18n project a few simple steps are required.
-
Create a google service account following authenticating as a service account manual
-
Download the service account credentials file (e.g.
credentials.json
), which should look like the following:
{
"type": "service_account",
"project_id": ####,
"private_key_id": ####,
"private_key":####,
"client_email": ####,
"client_id": ####,
"auth_uri": "####,
"token_uri": ####,
"auth_provider_x509_cert_url": ####,
"client_x509_cert_url": ####
}
- Update appropriate launch options' (which you're prefer to run) environment variables to use the service account credentials, e.g. if you use
IIS Express
option - update the following inGoogleSheetI18n.Api\Properties\launchSettings.json
:
"IIS Express": {
"environmentVariables": {
"GOOGLE_APPLICATION_CREDENTIALS": "c:\\Downloads\\credentials.json"
}
}
- Build the API and run it. There are no special dependencies or caveats so just restore Nuget packages before the build, and you should be fine.
Docker support
Pull and run
You may want to just pull and run a Docker image. To achieve that run the following commangs:
docker pull docker pull godeltech/googlesheeti18n:3661
*where 3661
is the desired tag at Docker Hub
docker run -i -e LOCAL_STORE_PATH="local-store" -e SPREADSHEET_ID="156UC1_Y2mwhGfY7Y-8RDiNM75eavFwzxBFNP9emNTzc" -e GOOGLE_APPLICATION_CREDENTIALS_AS_JSON=’{ "type": "service_account", ... }’ -e ASPNETCORE_ENVIRONMENT="Development" -p 8080:80 godeltech/googlesheeti18n:3661
*where GOOGLE_APPLICATION_CREDENTIALS_AS_JSON
's value is your personal full Google Application Credentials JSON (escaped, e.g. with double quotes "
look like \"
)
Build and run
Alternatively, you may want to build the docker image of the tool locally instead. To do that you will need a few commands mentioned below:
docker build .
docker run -i -e LOCAL_STORE_PATH="local-store" -e SPREADSHEET_ID="156UC1_Y2mwhGfY7Y-8RDiNM75eavFwzxBFNP9emNTzc" -e GOOGLE_APPLICATION_CREDENTIALS_AS_JSON=’{ "type": "service_account", ... }’ -e ASPNETCORE_ENVIRONMENT="Development" -p 8080:80
Sample Web client
-
Restore npm packages in
samples\WebClient
by runningnpm install
-
Start the client by running
npm start
in the same folder. It will host and run the application in development mode at http://localhost:3000. -
Or use docker-compose
docker-compose up
Production use notes
There are a few thing you should know before you start.
We fetch all the options from GoogleSheetI18n\src\GoogleSheetI18n.Api\appsettings.json
, GoogleSheetI18n.Api\Properties\launchSettings.json
files and/or environment variables
We use Google Sheets as a storage, so we expect a valid Google Sheet ID in either:
SpreadsheetId
value inappsettings.json
; ORSPREADSHEET_ID
environment variable.
We use Google cloud (service) credentials for accessing Google Sheets, so we expect them to be provided to the app. There are a few options:
- Via setting path to file with credentials to
GOOGLE_APPLICATION_CREDENTIALS
environment variable; OR - Via setting credentials encoded json into
GOOGLE_APPLICATION_CREDENTIALS_AS_JSON
environment variable; OR - Via setting path to file with credentails to
CredentialsFilePath
variable inappsettings.json
.
We currently use local file system for backups (local cache) as the only option, so let us know the folder via either:
LocalStoreFolderPath
value inappsettings.json
; ORBACKUP_FOLDER_PATH
environment variable.