Localization for Quail

[mlewand]

The current way to bring localization strings into QUAIL tests is cumbersome and non optimal. It has a strong impact on the QUAIL distribution size and on the ability of translators to contribute. This aspect must be redesigned.

We assume that current localization for en and nl is just a temporary solution. But now, when we want Quail to be widely used, it's time to bring a real solution for multiple localizations.

Issue #269 might be related.

[jessebeach]

Yes, localization as it stands is a very narrow solution. It was meant to be a bridge between no localization and a flexible solution.

[mlewand]

Alright so lets start proposing some concepts / solutions.

What needs to be localized?

• Core
  • error messages
  • testability strings
  • possibly assessment tags
• Assessments
  • title
  • description

Concept

The idea is to split localization into two files config and assessments.

• lang/en/core.json
• lang/en/assessments.json

Quail would load proper language file on demand (once $().quail is called with a given language).

Quail main object will store internal variable:

Quail._langs = {
    en: {
        core: {
            // Dictionary...
        },
        assessments: {
            // Dictionary...
        }
    },
    nl: {
        core: {
            // Dictionary...
        },
        assessments: {
            // Dictionary...
        }
    }
}

And localization values will be available with:

quail.lang( 'core.testability.moderate' );

Then for convenience Test collection would implement the following lang method:

Test.prototype.lang = function( propertyName ) {
    // Reminder: this.attributes.name stores assessment id, e.g. `imgHasAlt`.
    return this.quail.lang( 'assessments.' + this.attributes.name + '.' + propertyName );
}

Typical main Quail fn call might look sth like:

$( scope ).quail( {
    lang: 'en',
    resultsReady: function( results ) {
        // This method is called when checking is done and results are ready.
        // Result objects does **not contain any localizations** at this point. Only id, status.
    },
    resultsLoaded: function( results ) {
        // This method has the same role as `resultsLoaded`, but here developer can access
        // localized data (even synchronously).
        var failedCollection = collection.findByStatus( 'failed' );

        if ( failedCollection.length ) {
            failedCollection.each( function( index, test ) {
                // Note that we're accessing lang property synchronously here.
                console.log( test.lang( 'title' ) );
            } );
        }
    }
} );

Optimization: When building Quail, the builder will merge default lang's core.json into Quail output .js file. That way we don't need to request (wait) for core.json to start checking in case of default language.

Procedure

• $( scope ).quail() called with lang='en'.

  • Quail checks if quail._langs.en.core exists.

    • If true, go to the next step.
    • If false load lang/en/core.json. Once done store it and go to the next step.

  • If quail._langs.en.assessments is undefined, dispatch a request for lang/en/assessments.json and continue.

    The point here is start request for assessments.json so that it's downloaded during next step (Quail checking). There's a big chance that it's
    going to be done by the time that Quail finishes checking.

  • Start checking

  • Once checking is done:

    • Call options.resultsReady method (we don't need assessments.json here).
    • Check if quail._langs.en.assessments is defined:
      • If true go to the next step.
      • If false add a callback that will be called once assessments.json is loaded.
    • Call options.resultsLoaded.

Notes

• We need to implement a fallback in case if language (given to $( scope ).quail()` at runtime) was not found.

• Splitting assessment files

  Initially we wanted to split localization jsons per assessment, so that we'd have structure like:

  lang/en/assessments/aImgAltNotRepetitive.json
  lang/en/assessments/aAdjacentWithSameResourceShouldBeCombined.json
  lang/en/assessments/aInPhasADistinctStyle.json
  lang/en/assessments/aLinksDontOpenNewWindow.json
  lang/en/assessments/imgHasAlt.json
  

  But it would be useful only once Review on a11y tests directory structure #269 is done (putting assessments in their respective directory). In current shape it doesn't feel any better.

• Then again, where will metadata be kept? That makes me really want Review on a11y tests directory structure #269 to be done first :)

  I recall we were actually talking about dropping metadata completely. Actually we can't drop it, because it stores some vital information like type (selector, event etc) or testability.

  • Source - in source we can simply keep one file meta.json (or yml) that will store meta for all the assessments.
  • Built Quail - meta should be merged into main Quail js file. It's not big in terms of size, and it keeps some essential properties.

• At some point we might integrate some better l11n tool, like Transifex that will allow non-tech people to contribute langs, without messing with .json files and git. But I think we don't need it yet, simply json files will do for now. :)