RFC: Add State Module to options.config to enable multilingual routes

[cloudmark]

We want to support multilingual urls and hence we want to defer the url to state binding to be done at runtime rather than being performed statically. Imagine we have a sitemap service which retrieves the urls per states e.g.:

{
    'en': [
      {'module': 'app.home', 'path': ''},
      {'module': 'app.about', 'path': '/about'},
    ],
    'sv': [
      {'module': 'app.home', 'path': ''},
      {'module': 'app.about', 'path': '/om'}
    ]
  }

we want to wire the state app.home and app.about to /en and /en/about when the language is en and '/sv' and '/sv/om' when the language is '/sv'.

Looking at UIRouter.forRoot or UIRouter.forChild there is a options.config which could allow us to enable this behaviour which is called from the applyModuleConfig method:

function applyModuleConfig(uiRouter, injector, options) {
    if (options === void 0) { options = {}; }
    if (isFunction(options.config)) {
        options.config(uiRouter, injector);
    }
    var states = options.states || [];
    states.forEach(function (state) { return uiRouter.stateRegistry.register(state); });
}

What is stopping us from using this hook is the fact that options.config only takes uiRouter and injector as arguments.

Adding options (module) as a third parameter will allow us to achieve deferred route configuration.

export function applyModuleConfig(uiRouter: UIRouter, injector: Injector, options: StatesModule = {}) {
  if (isFunction(options.config)) {
    options.config(uiRouter, injector, options);
  }

  let states = options.states || [];
  states.forEach(state => uiRouter.stateRegistry.register(state));
}

Example

As an example of how this would work have a look at the ui-router-multilingual project

To run the project:

npm install
npm start.deving

Open the browser and goto http://localhost:5555/en and hover on the links HOME and ABOUT.

• HOME should point to /en/
• ABOUT should point to /en/about

Open the browser and goto http://localhost:5555/sv and hover on the links HOME and ABOUT.

• HOME should point to /sv/
• ABOUT should point to /sv/om

Opening directly the link http://localhost:5555/ will default to english.

To configure multilingual modules we would setup the forChild and forRoot we would add the uiRouterConfigureSitemap config function e.g.

@NgModule({
  imports: [CommonModule,
    UIRouterModule.forChild({
      states:CHILD_STATES,
      config: uiRouterConfigureSitemap
    })],
  declarations: [AboutComponent],
  exports: [AboutComponent]
})
export class AboutModule {
}

The config function is simple:

export function uiRouterConfigureSitemap(router: UIRouter, injector: Injector, module: StatesModule) {
  let states: ExtNg2StateDeclaration[] = <ExtNg2StateDeclaration[]>module.states;

  // Process the states;
  let filteredStates: ExtNg2StateDeclaration[] = _.filter(states, (s) => {
    return s.future && !s._complete
  });

  _.map(filteredStates, (s) => {
    let sitemapObj:any = _.find(getSitemap(), (sitemap:any) => sitemap.module == s.name);
    console.log(`Retrieved ${s.name} from sitemap ${sitemapObj.path}`);
    // Set the url from the sitemap object
    s.url = sitemapObj.path;
    s._complete = true;
  });
  router.urlService.config.strictMode(false);
}

Note that ui-router-ng2 is committed. node_modules/ui-router-ng2 includes the changes proposed in the Pull Request.

[christopherthielen]

I've been thinking about this and think the proposal for passing in the module is fine.

I'm wondering about your multilingual url approach however. How do you intend to support sharing of deep links, but using the end user's preferred language?

For example, if a swedish user shares /sv/om with an english user, what does the english user see? Have you also considered how to handle a "default" language?

[cloudmark]

The example above already supports a "default" language, if a language is not specified the :lang property will default to "en". On the actual site (written in angular v1) we have a hard redirect before the angular application even boots up so that this situation is a bit more clear to the end user.

export default function onBoot() {
    let dfrPlayer = $.Deferred();
    let dfrSitemap = $.Deferred();
    let currentPath = location.pathname + location.hash;
    let matches = currentPath.match('^\/(en|fi|sv|no)\/.*');
    let language;
    if (!matches) {
        location.assign(location.protocol + '//' + location.host + '/sv/');
       // or redirect using some data present in the cookies :)
    } else {
        language = matches[1];
        HttpService.language = language;
        console.log("Loading Sitemap");
        loadSitemap(dfrPlayer, language, 1);
        loadPlayer(dfrSitemap, language, 1);
    }
    return $.when(dfrPlayer, dfrSitemap);
}

One way to handle translation on the FE side is as follows (consider this a thought experiment):

When a Swedish user shares /sv/om and this link is opened by an english user we would first retrieve the module associated with /sv/om (app.about) and lookup the english path equivalent i.e. /en/about. This represents the simplest case since there are no param values present in the state.

Given the following sitemap:

{
    'en': [
      ...
      {'module': 'app.games', 'path': '/games/:gameId'}
    ],
    'sv': [
      ...
      {'module': 'app.games', 'path': '/spella/:gameId'}
    ]
  }

lets assume that a user shared /spella/123. This is a bit more complex since there are parameters involved which need to be remapped.

The url resolution would work as follows:

1. Load the module associated with /spella/123 i.e. app.games and lookup the English equivalent i.e. /games/:gameId. Perhaps make use of the UrlMatcher and UrlMatcherFactory class to do this.
2. Determine the parameters of /spella/123 given the generic url /spella/:gameId in order to map out the parameters. This would result in {"gameId": 123}
3. Template the parameters on the path /games/:gameId fully transforming the path to /games/123
4. Redirect.

Another possible way to handle this is via the sitemap itself. When a user loads a sitemap we return the alternate urls for each language as follows:

{
    'en': [
      {'module': 'app.home', 'path': '', 
          "alternate": {
             "sv": ""
           }
      },
      {'module': 'app.about', 'path': '/about', 
          "alternate": {
             "sv": "/om"
           }
      },
    ],
    ...  
}

This might work if the url space is relatively small.

I think the main point here is that people will choose to do this in different ways and trying to find a specific solution will inevitably lead to opinions. The

You can please some of the people all of the time, you can please all of the people some of the time, but you can’t please all of the people all of the time

situation.

Allowing the options.config to receive the state module would enable a multi-lingual provider a hook to resolve urls. Translating the urls needs to be tackled separately IMO. It could very well be that passing the state module in the options.configmight help the translation process but some people might choose a naive approach as demonstrated in the sitemap with the alternate case.

In a way I feel that the ui-router should be responsible for the hook and leave the actual translation strategies open. You are a better judge than me of course and I'd love to hear your opinion.

[cloudmark]

What are you thoughts on this @christopherthielen?

[christopherthielen]

people will choose to do this in different ways and trying to find a specific solution will inevitably lead to opinions

I feel that the ui-router should be responsible for the hook and leave the actual translation strategies open.

Completely agree with these statements

---

Here's a proof of concept in ng1: http://plnkr.co/edit/cIVAcI9ky5a7BOTsa7b6?p=preview

It uses urlmatcher to register a bunch of redirects (one for each state + language combo). It redirects to the language stored in localstorage.