Skip to content
Permalink
Browse files

Add documentation for configuration and development

  • Loading branch information...
blyszcz committed Sep 4, 2018
1 parent 5fcec17 commit d2b601aee7f69d05c8ac9e5b67d9e5ff605fe565
Showing with 7,263 additions and 26 deletions.
  1. +22 −17 docs-src/configuration.md
  2. +50 −0 docs-src/development.md
  3. +4 −4 docs-src/docker.md
  4. +1 −1 docs-src/index.md
  5. +22 −3 docs-src/services.md
  6. +298 −0 docs/404.html
  7. +4 −0 docs/assets/fonts/font-awesome.css
  8. +13 −0 docs/assets/fonts/material-icons.css
  9. BIN docs/assets/fonts/specimen/FontAwesome.ttf
  10. BIN docs/assets/fonts/specimen/FontAwesome.woff
  11. BIN docs/assets/fonts/specimen/FontAwesome.woff2
  12. BIN docs/assets/fonts/specimen/MaterialIcons-Regular.ttf
  13. BIN docs/assets/fonts/specimen/MaterialIcons-Regular.woff
  14. BIN docs/assets/fonts/specimen/MaterialIcons-Regular.woff2
  15. BIN docs/assets/images/favicon.png
  16. +20 −0 docs/assets/images/icons/bitbucket.1b09e088.svg
  17. +18 −0 docs/assets/images/icons/github.f0b8504a.svg
  18. +38 −0 docs/assets/images/icons/gitlab.6dd19c00.svg
  19. +1 −0 docs/assets/javascripts/application.583bbe55.js
  20. +1 −0 docs/assets/javascripts/lunr/lunr.da.js
  21. +1 −0 docs/assets/javascripts/lunr/lunr.de.js
  22. +1 −0 docs/assets/javascripts/lunr/lunr.du.js
  23. +1 −0 docs/assets/javascripts/lunr/lunr.es.js
  24. +1 −0 docs/assets/javascripts/lunr/lunr.fi.js
  25. +1 −0 docs/assets/javascripts/lunr/lunr.fr.js
  26. +1 −0 docs/assets/javascripts/lunr/lunr.hu.js
  27. +1 −0 docs/assets/javascripts/lunr/lunr.it.js
  28. +1 −0 docs/assets/javascripts/lunr/lunr.jp.js
  29. +1 −0 docs/assets/javascripts/lunr/lunr.multi.js
  30. +1 −0 docs/assets/javascripts/lunr/lunr.no.js
  31. +1 −0 docs/assets/javascripts/lunr/lunr.pt.js
  32. +1 −0 docs/assets/javascripts/lunr/lunr.ro.js
  33. +1 −0 docs/assets/javascripts/lunr/lunr.ru.js
  34. +1 −0 docs/assets/javascripts/lunr/lunr.stemmer.support.js
  35. +1 −0 docs/assets/javascripts/lunr/lunr.sv.js
  36. +1 −0 docs/assets/javascripts/lunr/lunr.tr.js
  37. +1 −0 docs/assets/javascripts/lunr/tinyseg.js
  38. +1 −0 docs/assets/javascripts/modernizr.1aa3b519.js
  39. +1,176 −0 docs/assets/stylesheets/application-palette.22915126.css
  40. +2,552 −0 docs/assets/stylesheets/application.451f80e5.css
  41. +546 −0 docs/configuration/index.html
  42. +454 −0 docs/development/index.html
  43. +484 −0 docs/docker/index.html
  44. +417 −0 docs/how-it-works/index.html
  45. BIN docs/img/spreadsheet-name.png
  46. +435 −0 docs/index.html
  47. +1 −0 docs/search/search_index.json
  48. +644 −0 docs/services/index.html
  49. +33 −0 docs/sitemap.xml
  50. BIN docs/sitemap.xml.gz
  51. +11 −1 mkdocs.yml
@@ -1,4 +1,4 @@
In order to start using babelsheet, you have to configure your .env file first.
In order to start using babelsheet, you have to configure your `.env` file first.

## Configuration file

@@ -39,7 +39,7 @@ TRACING_SERVICE_PORT=6832
<details>
<summary id="how-to-get-spreadsheet-name">How to get spreadsheet name</summary>
<p>
Spreadsheet name is the name of the tab in spreadsheet document
Spreadsheet name is the name of the tab in spreadsheet document.
![Screenshot](img/spreadsheet-name.png)
</p>
</details>
@@ -82,21 +82,26 @@ TRACING_SERVICE_PORT=6832

1. To generate refresh token, you have to [configure Google Spreadsheet API](#configuring-google-spreadsheet-api) first.
2. When `CLIENT_ID` and `CLIENT_SECRET` are stored in `.env` file, you are ready to generate refresh-token.
3. Run `npm generate --config`.
<details>
<summary>Config in json file</summary>
<p>
You can also generate token in `data.json` file, just by passing `json` parameter option `npm generate --config json`.
</p>
</details>
<details>
<summary>CLIENT_ID and CLIENT_SECRET as params</summary>
<p>
You don't have to create .env file, you can pass CLIENT_ID and CLIENT_SECRET values as parameters to babelsheet:
`npm generate --config --client_id <yours-client-id> --client_secret <yours-client-secret>`
</p>
</details>
3. Run `babelsheet generate --config`.


<small>If babelsheet is not installed, run `npm i -g babelsheet` to install.</small>
<details>
<summary>CLIENT_ID and CLIENT_SECRET as params</summary>
<p>
You don't have to create .env file, you can pass CLIENT_ID and CLIENT_SECRET values as parameters to babelsheet:
`npm generate --config --client_id <yours-client-id> --client_secret <yours-client-secret>`
</p>
</details>
<details>
<summary>Config in json file</summary>
<p>
You can also generate token in `data.json` file, just by passing `json` parameter option `npm generate --config json`.
</p>
</details>


4. Browser window will be opened automatically. Log in into you Google account and then grant your application an access for reading spreadsheets in your account. You should be given a message `Authentication successful! Please return to the console`.
5. Refresh token is now stored in `.env` file.
5. Refresh token is now stored in `.env` file. You can change storage type [here](#set-refresh-token-write-provider).
6. More actions won't be needed because tokens will be refreshed automatically if necessary.

@@ -0,0 +1,50 @@
## Set refresh token read providers
You can set order of `REFRESH_TOKEN` providers in `/src/services/producer/container.ts` for producer, and in `/src/services/cli/container.ts` for CLI tool:

```
readProviders: [
container.resolve<InEnvStorage>('inEnvStorage'),
container.resolve<InFileStorage>('inFileStorage'),
container.resolve<InRedisStorage>('inRedisStorage'),
],
```
First .env file will be checked does it contain `REFRESH_TOKEN`, if not, next `data.json` file will be checked, and the last one will be redis storage. Feel free to change order of those providers, or creating new ones.


## Set refresh token write provider
You can set `REFRESH_TOKEN` write provider in `/src/services/cli/container.ts` for CLI tool, and in `/src/services/producer/container.ts` for producer. Notice that producer will only have ability to save `REFRESH_TOKEN` when you run it locally, not in docker container - browser window will be opened automatically.

`writeProvider: container.resolve<InEnvStorage>('inEnvStorage'),`

You can change it to one of those three storages:

`container.resolve<InEnvStorage>('inEnvStorage')`

`container.resolve<InFileStorage>('inFileStorage')`

`container.resolve<InRedisStorage>('inRedisStorage')`

Feel free to add new providers.


## Change translations storage from redis to file
By default, translations as saved in redis storage. In order to change translations storage to file.

1. Open `/src/services/producer/container.ts` and change:

`storage: awilix.asClass(InRedisStorage)` to:

```
storage: awilix.asClass(InFileStorage)
```

2. Open `/src/services/api/container.ts` and change:

`storage: awilix.asClass(InFileStorage)` to:

```
fileRepository: awilix.asClass(FileRepository, { lifetime: awilix.Lifetime.SINGLETON }),
storage: awilix.asClass(InFileStorage)
```

Producer will now save to `data.json` file, and API will read from that file as well.
@@ -25,22 +25,22 @@ services:
- "6379:6379"
```

Next, make sure you have proper [.env file](/../configuration#configuration-file) in the same directory, then run `docker-compose up`, and API should be working now.
Next, make sure you have proper [.env](/../configuration#configuration-file) file in the same directory, then run `docker-compose up`, and API should be working now.

## Redis
To run redis as a docker container type
`docker run --name redis -p 6379:6379 redis`

Or run it from [docker-compose.yml file](#docker-compose) by following command:
Or run it from [docker-compose.yml](#docker-compose) file by following command:

`docker-compose up redis`

## Producer
To run producer from [docker-compose.yml file](#docker-compose) run following command:
To run producer from [docker-compose.yml](#docker-compose) file run following command:

`docker-compose up babelsheet-producer`

## API
To run API from [docker-compose.yml file](#docker-compose) run following command:
To run API from [docker-compose.yml](#docker-compose) file run following command:

`docker-compose up babelsheet-api`
@@ -11,7 +11,7 @@ No more dealing with complicated paid translation services or problems with mult
2. `npm i -g babelsheet`
3. `babelsheet generate`

## To run as API
## To run API

1. Create [configuration file](/../configuration#configuration-file).
2. Create [docker-compose.yml](/../docker#docker-compose).
@@ -19,6 +19,10 @@ To generate translations type:

`babelsheet generate [options]`

Remember to [create .env file](/../configuration#configuration-file) before generating translations.

<small>If you wont provide `REFRESH_TOKEN` in `.env` file or `data.json` file, babelsheet will automatically open browser to create such token, and save will save it in right storage - you can change read and write storages, check it [here](/../configuration#set-refresh-token-read-providers).</small>

**Options**
<details>
<summary>--format</summary>
@@ -62,7 +66,7 @@ To generate translations type:
(default: <code>translations</code>)
</p>
<p>
Filename of final translati3on file.
Filename of final translation file.
</p>
</details>
<details>
@@ -123,7 +127,6 @@ To generate translations type:

`babelsheet generate --format ios --path ./translations` - generates translations in iOS format in translations folder.


## Producer
Producer is used to fetch translations file, convert it and then store it in a database. The process is wrapped in a scheduler which repeats the whole operation continuously every 5 minutes. Please note that if there are no proper environment variables such as `CLIENT_ID`, `CLIENT_SECRET` and `REFRESH_TOKEN` then producer is not able to work properly. In such case it runs a command responsible for obtaining those keys.

@@ -137,8 +140,17 @@ If you want to run producer locally, first remember about [setting environment v

Producer should be working now.

You can change `REFRESH_TOKEN` read and write providers, check it [here](/../development#set-refresh-token-read-providers).

You can also change translations storage from redis to file, check it [here](/../development#change-translations-storage-from-redis-to-file).

## API
API is a web server built on top of `express.js` which serves translations. There is one endpoint available to obtain translations, which is `/translations`, but they can be also filtered by using query param filter, e.g. calling `/translations?filters[]=en_US.CORE` will result in getting translations for `en_US` locale and section `CORE`. Other possibility is to use tag as a filter, e.g. `/translations?filters[]=en_US.tag1`. Translations are served in json format and the structure is preserved regardless of filters being used.
API is a web server built on top of `express.js` which serves translations. There is one endpoint available to obtain translations, which is `/translations`.
Translations can be filtered by using:

- `filters[]` - e.g. calling `/translations?filters[]=en_US.CORE` will result in getting translations for `en_US` locale and section `CORE`. Other possibility is to use tag as a filter, e.g. `/translations?filters[]=en_US.tag1`.

- `format` - translations can be served in json/android/ios formats, just add adtitional parameter e.g. `/translations?filters[]=en_US.CORE&format=android`.

You can run API in docker container - see [Docker](/../docker#).

@@ -149,3 +161,10 @@ If you want to run API locally, first remember about [setting environment variab
2. `npm run dev-start-api`

API should be working now.

### Usage
```
curl -X GET -g 'http://localhost:3000/translations'
curl -X GET -g 'http://localhost:3000/translations?filters[]=en_US.CORE'
curl -X GET -g 'http://localhost:3000/translations?filters[]=en_US.CORE.LABELS&format=android'
```
Oops, something went wrong.

0 comments on commit d2b601a

Please sign in to comment.
You can’t perform that action at this time.