Skip to content
Snippets Groups Projects
Unverified Commit 51452399 authored by Kyle Doherty's avatar Kyle Doherty Committed by GitHub
Browse files

improve i18n workflow documentation (#9160) 

* improve i18n workflow documentation

* fix a typo

* clear up copy
parent 258bce27
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
.github/PULL_REQUEST_TEMPLATE.md
+ 5
− 2
View file @ 51452399
###### Before submitting the PR, please make sure you do the following
- [ ] If there are changes to the backend codebase, run the backend tests with `lein test && lein eastwood && lein bikeshed && lein docstring-checker && ./bin/reflection-linter`
###### Before submitting the PR, please make sure you do the following
- [ ] If you're attempting to fix a translation issue, please submit your changes to our [POEditor project](https://poeditor.com/join/project/ynjQmwSsGh) instead of opening a PR.
### Tests
- [ ] Run the frontend and integration tests with `yarn lint && yarn flow && yarn test`)
- [ ] If there are changes to the backend codebase, run the backend tests with `lein test && lein eastwood && lein bikeshed && lein docstring-checker && ./bin/reflection-linter`
- [ ] Sign the [Contributor License Agreement](https://docs.google.com/a/metabase.com/forms/d/1oV38o7b9ONFSwuzwmERRMi9SYrhYeOrkbmNaq9pOJ_E/viewform)
(unless it's a tiny documentation change).
docs/developers-guide.md
+ 27
− 35
View file @ 51452399
**This guide will teach you:**
* [How to compile your own copy of Metabase](#build-metabase)
* [How to set up a development environment](#development-environment)
* [How to run the Metabase Server](#development-server-quick-start)
* [How to contribute back to the Metabase project](#contributing)
* [How to add support in Metabase for other languages](#internationalization)
* [How to compile your own copy of Metabase](#build-metabase)
* [How to set up a development environment](#development-environment)
* [How to run the Metabase Server](#development-server-quick-start)
* [How to contribute back to the Metabase project](#contributing)
* [How to add support in Metabase for other languages](#internationalization)
# Contributing
......@@ -23,18 +22,18 @@ If you have problems with your development environment, make sure that you are n
# Install Prerequisites
These are the set of tools which are required in order to complete any build of the Metabase code. Follow the links to download and install them on your own before continuing.
These are the set of tools which are required in order to complete any build of the Metabase code. Follow the links to download and install them on your own before continuing.
1. [Oracle JDK 8 (http://www.oracle.com/technetwork/java/javase/downloads/index.html)](http://www.oracle.com/technetwork/java/javase/downloads/index.html)
2. [Node.js (http://nodejs.org/)](http://nodejs.org/)
3. [Yarn package manager for Node.js](https://yarnpkg.com/)
3. [Leiningen (http://leiningen.org/)](http://leiningen.org/)
4. [Leiningen (http://leiningen.org/)](http://leiningen.org/)
If you are developing on Windows, make sure to use Ubuntu on Windows and follow instructions for Ubuntu/Linux instead of installing ordinary Windows versions.
# Build Metabase
The entire Metabase application is compiled and assembled into a single .jar file which can run on any modern JVM. There is a script which will execute all steps in the process and output the final artifact for you.
The entire Metabase application is compiled and assembled into a single .jar file which can run on any modern JVM. There is a script which will execute all steps in the process and output the final artifact for you.
./bin/build
......@@ -44,7 +43,6 @@ After running the build script simply look in `target/uberjar` for the output .j
See [this guide](developers-guide-osx.md).
# Development Environment
If you plan to work on the Metabase code and make changes then you'll need to understand a few more things.
......@@ -78,13 +76,14 @@ Start the frontend build process with
yarn run build-hot
## Frontend development
We use these technologies for our FE build process to allow us to use modules, es6 syntax, and css variables.
- webpack
- babel
- cssnext
* webpack
* babel
* cssnext
Frontend tasks are executed using `yarn run`. All available tasks can be found in `package.json` under *scripts*.
Frontend tasks are executed using `yarn run`. All available tasks can be found in `package.json` under _scripts_.
To build the frontend client without watching for changes, you can use:
......@@ -117,11 +116,13 @@ yarn run test
which will first build the backend JAR and then run integration, unit and Karma browser tests in sequence.
### Jest integration tests
Integration tests simulate realistic sequences of user interactions. They render a complete DOM tree using [Enzyme](http://airbnb.io/enzyme/docs/api/index.html) and use temporary backend instances for executing API calls.
Integration tests use an enforced file naming convention `<test-suite-name>.integ.js` to separate them from unit tests.
Useful commands:
```bash
lein run refresh-integration-test-db-metadata # Scan the sample dataset and re-run sync/classification/field values caching
yarn run test-integrated-watch # Watches for file changes and runs the tests that have changed
......@@ -185,12 +186,10 @@ describe("Query builder", () => {
// to click links that lead to other router paths.
});
})
```
You can also skim through [`__support__/integrated_tests.js`](https://github.com/metabase/metabase/blob/master/frontend/test/__support__/integrated_tests.js) and [`__support__/enzyme_utils.js`](https://github.com/metabase/metabase/blob/master/frontend/test/__support__/enzyme_utils.js) to see all available methods.
### Jest unit tests
Unit tests are focused around isolated parts of business logic.
......@@ -203,6 +202,7 @@ yarn run test-unit-watch # Watch for file changes
```
### Karma browser tests
If you need to test code which uses browser APIs that are only available in real browsers, you can add a Karma test to `frontend/test/legacy-karma` directory.
```
......@@ -211,6 +211,7 @@ yarn run test-karma-watch # Watch for file changes
```
## Backend development
Leiningen and your REPL are the main development tools for the backend. There are some directions below on how to setup your REPL for easier development.
And of course your Jetty development server is available via
......@@ -242,7 +243,7 @@ need to build these drivers in order to have access to them. You can build drive
The first time you build a driver, it will be a bit slow, because Metabase needs to build the core project a couple of times so the driver can use it as a dependency; you can take comfort in the
fact that you won't need to build the driver again after that. Alternatively, running Metabase 1.0+ from the uberjar will unpack all of the pre-built drivers into your plugins directory; you can
do this instead if you already have a Metabase uberjar (just make sure `plugins` is in the root directory of the Metabase source, i.e. the same directory as `project.clj`).
do this instead if you already have a Metabase uberjar (just make sure `plugins` is in the root directory of the Metabase source, i.e. the same directory as `project.clj`).
### Including driver source paths for development or other Leiningen tasks
......@@ -259,7 +260,6 @@ When developing with Emacs and CIDER sending the universal prefix argument to `c
to start the NREPL process; you can add `with-profiles +include-all-drivers` to that command to include driver source paths, which will let you work on the core Metabase project and all of
the subprojects from a single REPL. :sunglasses:
#### Unit Tests / Linting
Run unit tests with
......@@ -280,7 +280,6 @@ Some drivers require additional environment variables when testing since they ar
lein eastwood && lein bikeshed && lein docstring-checker && ./bin/reflection-linter
#### Developing with Emacs
`.dir-locals.el` contains some Emacs Lisp that tells `clojure-mode` how to indent Metabase macros and which arguments are docstrings. Whenever this file is updated,
......@@ -304,14 +303,18 @@ Start up an instant cheatsheet for the project + dependencies by running
lein instant-cheatsheet
## Internationalization
We are an application with lots of users all over the world. To help them use Metabase in their own language, we mark all of our strings as i18n.
### The general workflow for developers is:
### Adding new strings:
If you need to add new strings (try to be judicious about adding copy) do the following:
1. Tag strings in the frontend using `t` and `jt` ES6 template literals (see more details in https://c-3po.js.org/):
```javascript
const someString = t`Hello ${name}!`;
const someJSX = <div>{ jt`Hello ${name}` }</div>
const someJSX = <div>{jt`Hello ${name}`}</div>;
```
and in the backend using `trs` and related macros (see more details in https://github.com/puppetlabs/clj-i18n):
......@@ -320,23 +323,12 @@ and in the backend using `trs` and related macros (see more details in https://g
(trs "Hello {0}!" name)
```
2. When you have added/edited tagged strings in the code, run `./bin/i18n/update-translations` to update the base `locales/metabase.pot` template and each existing `locales/LOCALE.po`
### The workflow for translators in starting a new translation, or editing an existing one:
1. You should run `./bin/i18n/update-translations` first to ensure the latest strings have been extracted.
2. If you're starting a new translation or didn't run update-translations then run `./bin/i18n/update-translation LOCALE`
3. Edit ./locales/LOCALE.po
4. `Run ./bin/i18n/build-translation-resources`
5. Restart or rebuild Metabase, Test, repeat 2 and 3
6. Commit changes to ./locales/LOCALE.po and ./resources/frontend_client/app/locales/LOCALE.json
To try it out, change your browser's language (e.x. chrome://settings/?search=language) to one of the locales to see it working. Run metabase with the `JAVA_TOOL_OPTIONS=-Duser.language=LOCALE` environment variable set to set the locale on the backend, e.x. for pulses and emails (eventually we'll also add a setting in the app)
### Translation errors or missing strings
If you see incorrect or missing strings for your langauge, please visit our [POEditor project](https://poeditor.com/join/project/ynjQmwSsGh) and submit your fixes there.
## License
Copyright © 2017 Metabase, Inc
Distributed under the terms of the GNU Affero General Public License (AGPL) except as otherwise noted. See individual files for details.
Distributed under the terms of the GNU Affero General Public License (AGPL) except as otherwise noted. See individual files for details.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment