# ab-translate
Quickly create AB Tests for texts without coding via [Wix Babel](https://bo.wix.com/wow/babel) & [Guineapig (Petri)](https://bo.wix.com/petri).

The process requries two simple steps:
1. [**Setup**](#setup) - one time config for a project to support the AB Translate flow
2. [**Create AB Test**](#create-ab-test) - create as many text tests as you or your Writer needs without writing a single line of code!!!!1 😱

## How it works
1. [Babel](https://bo.wix.com/wow/babel) creates a new translation key to your `messages_en.json` file in the git repo
2. [`petri-specs`](https://github.com/wix-private/fed-infra/tree/master/petri-specs) or Grunt `petriExperiments` task create a new spec once find the key in your `messages_en.json` file

## Setup
Do this once, for each project that you want to run translations tests in

### Yoshi (new stack)
1. Install the package `npm i ab-translate --save` or `yarn add ab-translate`

2. Configure the specs defaults for [`petri-specs`](https://github.com/wix-private/fed-infra/tree/master/petri-specs) in `.petrirc`/`petri.config.js` file


```json5
// .petrirc
    {
      "abTranslate": {
        "onlyForLoggedInUsers": false, // default: true
        "scopes": ["my-projects-translation-scope"], // default: [<artifactId>]
        "owner": "my-ownership-tag" // default: author from package.json
      }
    }
```

3. Save the petri experiments object to the window (e.g. `window.__EXPERIMENTS__ = '<%= experiments %>';`). *Notice:* make sure that you conduct the experiments for the scope in step #2

4. In the `src/i18n.js` file add the following code to the backend task ([example](https://github.com/wix-private/account-recovery/blob/master/src/i18n/client-i18n.js#L22))
    ```javascript
    import abTranslate from 'ab-translate/dist/src/abTranslate-runtime';

    backend: {
      crossDomain: true,
      parse: translations => {
        try {
          return abTranslate(window.__EXPERIMENTS__, JSON.parse(translations));
        } catch (e) {
          return JSON.parse(translations);
        }
      }
    }
    ```

5. In case Universal project is used with SSR, the change needs to be on the `middleware-i18n.js` **instead**, see example [here](https://github.com/wix-private/photography/blob/master/logo-builder/logo-builder-universal/src/i18n/middleware-i18n.js)


### Wix Grunt (old stack)
1. Install the package `bower install ab-translate --save`

2. Configure the specs defaults in your local `Gruntfile.js` file:
    ```javascript
    grunt.modifyTask('petriExperiments', {
      options: {
        onlyForLoggedInUsers: false, // default: true
        scopes: ['my-projects-translation-scope'], // default: [<artifactId>]
        owner: 'my-ownership-tag' // default: author from package.json
      }
    });
    ```

3. Add the Angular `abTranslateProvider` to your `index.vm` file ([example](https://github.com/wix-private/site-generator-statics-consumer/blob/00f9120d1964725aa3a89217f48978264210caa2/app/index.vm#L189))
    ```html
    <script src="bower_components/ab-translate/abTranslate.angular-runtime.bundle.min.js"></script>
    ```

4. Transform the translations using the `abTranslateProvider` and the project's `experimentManagerProvider` ([example](https://github.com/wix-private/site-generator-statics-consumer/blob/15d0f98603a575b5eda742ede781cf63f791f04b/app/scripts/app.ts#L80)). *Notice:* make sure that you conduct the experiments for the scope in step #2
    ```javascript
    angular.module('myApp', ['wix.ab-translate'])
      .config(function($translateProvider, abTranslateProvider, experimentManagerProvider) {
        const preferredLanguage = $translateProvider.preferredLanguage();
        const translations = $translateProvider.translations()[preferredLanguage];
        const translationsWithExperiments = abTranslateProvider.abTranslate.default(
          experimentManagerProvider.experiments,
          translations
        );
        $translateProvider.translations(preferredLanguage, translationsWithExperiments);
      });
    ```

## Create AB Test

1. Go to the [Babel translation system](https://bo.wix.com/wow/babel)

2. Select your project in the `Current Project` dropdown and select the `Update` tab
    ![Babel Home](docs/1.babel.home.png)

3. Look for the translation key you want to create a test for and click on the `Edit` icon button
    ![Update key](docs/2.update.keys.png)

4. Click on the `+ Add AB test to Key` button at the bottom of the modal
    ![Create AB Test](docs/3.babel.edit.png)

5. Pick spec name or create a new one.

    * `shorterSubTitle` will become `specs.abTranslate.<my-projects-translation-scope>.abSpec-shorterSubTitle`)
    * `<my-projects-translation-scope>` is the one defined in `package.json` -> `yoshi` -> `petriScopes` (or artifact id by default).

    ![Create spec](docs/4.babel.add.spec.png)

6. Add as many alternatives as you want
    ![Add Alternatives](docs/4.babel.add.variations.png)

7. Click the `Save changes` button.

   Babel will add new keys in format:

   ```json5
   {
     "<translatioKey>": "<Your Default A translation variant>",

     // New added keys
     "<translatioKey>|abTranslate_1|<yourSpec>": "<Your B translation variant>",
     "<translatioKey>|abTranslate_2|<yourSpec>": "<Your C translation variant>",
   }
   ```

8. A `"AB"` sign should appear next to your key. You can pick your AB Specs from the list
    ![Commit Changes](docs/5.babel.abSpecs.list.png)

9. The changes will be pushed to github and a new build will be triggered. The new AB test will be detected and will be created.

10. After the **Build** of the project you'll be able to see the spec in [Guineapig](https://bo.wix.com/petri). The spec name will be in the format `specs.abTranslate.<scope>.abSpec-<key>`.

11. Create an experiment and use [Petri Sidekick](https://chrome.google.com/webstore/detail/wix-petri-sidekick/hpdjckcenihbjfmaccadiaighajcjope) to verify the variations!

**Note1:** When creating the experiment verify that you open it only for the languages where the keys were updated

**Note2:** If the experiment is paused/killed/theres a bug in the system the first alternative (String #0) will be chosen so there shouldn't be any risks with this mechanism.

### Experiments in languages other than EN
Creating an experiment in other languages is possible, however there's a few things you should keep in mind:
1. Make sure that all variations are translated otherwise you'll have some variations fallback to English
2. When you merge a multi-lingual experiment the winner for each language might be different (in some languages A may win, while in other languages B, or C, etc). Keep that in mind when you get to that point. We hope to make your life easier with an auto-merge flow in the future :)

## Credits
* Guild Week Stars ✨
  * [@GuySopher](https://github.com/guysopher)
  * [@Yairhaimo](https://github.com/yairhaimo)
* FED Infra Team