ab-translate

ab-translate

Quickly create AB Tests for texts without coding via Wix Babel & Guineapig (Petri).

The process requries two simple steps:

1. Setup - one time config for a project to support the AB Translate flow
2. 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 creates a new translation key to your messages_en.json file in the git repo
2. 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 in .petrirc/petri.config.js file

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

1. 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

2. In the src/i18n.js file add the following code to the backend task (example)

   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);
       }
     }
   }
   

3. In case Universal project is used with SSR, the change needs to be on the middleware-i18n.js instead, see example here

Wix Grunt (old stack)

1. Install the package bower install ab-translate --save

2. Configure the specs defaults in your local Gruntfile.js file:

   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)

   <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). Notice: make sure that you conduct the experiments for the scope in step #2

   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

2. Select your project in the Current Project dropdown and select the Update tab

3. Look for the translation key you want to create a test for and click on the Edit icon button

4. Click on the + Add AB test to Key button at the bottom of the modal

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).

   

6. Add as many alternatives as you want

7. Click the Save changes button.

   Babel will add new keys in format:

   {
     "<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

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. The spec name will be in the format specs.abTranslate.<scope>.abSpec-<key>.

11. Create an experiment and use Petri Sidekick 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
  • @Yairhaimo
• FED Infra Team