Writing a list of examples for common webspace architectures and just wondering if I got this right. Please take the time to look at the various definitions, especially language and URL stuff, and let me know if I got things wrong anywhere.

Scenario:

International Corporation

Suppose Acme is an international corporation, and needs a Swiss web presence in 4 languages, a German web presence in one language, and a general corporate website for the rest of the world that's in English but also has German language available. Further, let's assume Acme needs the Swiss and German web presences to have their own domains, and the corp one should be acme.com/ for English and acme.com/de for German.

The solution? A single webspace with multiple portals. Here's the full file:

<?xml version="1.0" encoding="utf-8"?>
<webspace xmlns="http://schemas.sulu.io/webspace/webspace"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://schemas.sulu.io/webspace/webspace http://schemas.sulu.io/webspace/webspace-1.0.xsd">

    <name>acme.app</name>
    <key>acme-app</key>

    <localizations>
        <localization language="en" shadow="auto">
            <localization language="en" country="us" shadow="auto"/>
            <localization language="en" country="gb" shadow="auto"/>
        </localization>
        <localization language="de">
            <localization language="de" country="ch"/>
        </localization>
        <localization language="rm">
            <localization language="rm" country="ch"/>
        </localization>
        <localization language="fr">
            <localization language="fr" country="ch"/>
        </localization>
        <localization language="it">
            <localization language="it" country="ch"/>
        </localization>
    </localizations>

    <theme>
        <key>default</key>
        <default-templates>
            <default-template type="page">default</default-template>
            <default-template type="homepage">overview</default-template>
        </default-templates>

        <error-templates>
            <error-template default="true">ClientWebsiteBundle:views:error.html.twig</error-template>
            <error-template code="404">ClientWebsiteBundle:views:error404.html.twig</error-template>
        </error-templates>
    </theme>

    <navigation>
        <contexts>
            <context key="main">
                <meta>
                    <title lang="de">Hauptnavigation</title>
                    <title lang="en">Mainnavigation</title>
                </meta>
            </context>
            <context key="footer">
                <meta>
                    <title lang="de">Footernavigation</title>
                    <title lang="en">Footernavigation</title>
                </meta>
            </context>
        </contexts>
    </navigation>

    <portals>
        <portal>
            <name>acme.ch</name>
            <key>acme_ch</key>
            <resource-locator>
                <strategy>tree</strategy>
            </resource-locator>

            <localizations>
                <localization language="de" default="true"/>
                <localization language="fr"/>
                <localization language="it"/>
                <localization language="rm"/>
            </localizations>

            <environments>
                <environment type="prod">
                    <urls>
                        <url language="de">acme.ch</url>
                        <url language="it">acme.ch/it</url>
                        <url language="fr">acme.ch/fr</url>
                        <url language="rm">acme.ch/rm</url>
                    </urls>
                </environment>
                <environment type="stage">
                    <urls>
                        <url>stage.acme.ch/{language}</url>
                    </urls>
                </environment>
                <environment type="dev">
                    <urls>
                        <url language="de">acme-local.ch</url>
                        <url language="it">acme-local.ch/it</url>
                        <url language="fr">acme-local.ch/fr</url>
                        <url language="rm">acme-local.ch/rm</url>
                    </urls>
                </environment>
            </environments>
        </portal>

        <portal>
            <name>acme.de</name>
            <key>acme_de</key>
            <resource-locator>
                <strategy>tree</strategy>
            </resource-locator>

            <localizations>
                <localization language="de" default="true"/>
            </localizations>

            <environments>
                <environment type="prod">
                    <urls>
                        <url language="de">acme.de</url>
                    </urls>
                </environment>
                <environment type="stage">
                    <urls>
                        <url>stage.acme.de</url>
                    </urls>
                </environment>
                <environment type="dev">
                    <urls>
                        <url language="de">acme-local.de</url>
                    </urls>
                </environment>
            </environments>
        </portal>

        <portal>
            <name>acme.com</name>
            <key>acme_com</key>
            <resource-locator>
                <strategy>tree</strategy>
            </resource-locator>

            <localizations>
                <localization language="en" default="true"/>
                <localization language="de"/>
            </localizations>

            <environments>
                <environment type="prod">
                    <urls>
                        <url language="en">acme.com</url>
                        <url language="de">acme.com/de</url>
                    </urls>
                </environment>
                <environment type="stage">
                    <urls>
                        <url language="en">stage.acme.com</url>
                        <url language="de">stage.acme.com/de</url>
                    </urls>
                </environment>
                <environment type="dev">
                    <urls>
                        <url language="en">acme-local.com</url>
                        <url language="de">acme-local.com/de</url>
                    </urls>
                </environment>
            </environments>
        </portal>

    </portals>
</webspace>

A few things I have noted (maybe @chirimoya and @wachterjohannes have more input):

Localizations

This way you would end up with 11 localizations. The nesting works a bit different, since all localizations in this tree are generated, so you would end up with en, en-us, en-gb, de, de_ch and so on, I guess you get the idea. I would build it something like this:

<localizations>
    <localization language="en" shadow="auto"/>
    <localization language="de" country="ch"/>
    <localization language="rm" country="ch"/>
    <localization language="fr" country="ch"/>
    <localization language="it" country="ch"/>
</localizations>

This way you get the localizations en, de-ch, rm-ch, fr-ch, it-ch. The nesting would make sense if you are publishing stuff in germany, austria and switzerland, like in the following example:

<localizations>
    <localization language="en"/>
    <localization language="de" country="de">
         <localization language="de" country="at"/>
         <localization language="de" country="ch"/>
    </localization>
</localizations>

This nesting will help the system to find better fallback languages, so if de-at is not created yet, it tries to load the fallback value from de-de before en.

Please tell if the explanation in the documentation is not sufficient.

URLs

You should favor {localization} over {language} in the URL definition, since it contains the combined value for the language and the optional country. {language} and {country} are existing for cases where you build more complex URLs like {language}.acme.{country}, which could then be resolved to de.acme.at, fr.acme.ch, de.acme.ch, ...

FYI: This {localization} placeholder could also be used for your other urls. So instead of:

<urls>
    <url language="de">acme.ch</url>
    <url language="it">acme.ch/it</url>
    <url language="fr">acme.ch/fr</url>
    <url language="rm">acme.ch/rm</url>
</urls>

You could simply write:

<urls>
    <url>acme.ch/{localization}</url>
</urls>

One drawback of this method is that acme.ch will not show the german content, but redirect to the default localization. I thought we already have an issue, where we discussed changing that, but I couldn't find it now... I think we should make that configureable.

Resource Locator Strategy

That's a note for us: I think it is wrong to have this setting on the portal, since the URL is tight to the page itself. It might be possible to generate the URL in different ways, but that makes the handling utterly complex, and won't work as it currently is.

The nesting would make sense if you are publishing stuff in germany, austria and switzerland,

Yes, the corporation does publish stuff in Austria, Germany and Switzerland. I have not explained adequately - when I say "X web presence", it means "website in X country", so to speak.

Please tell if the explanation in the documentation is not sufficient.

It isn't - that's the text I followed trying to make this work. Looks like I got it wrong :)

One drawback of this method is that acme.ch will not show the german content, but redirect to the default localization.

Can you give me an example of that? I'm not sure I understand what this means.

Resource locator: I think it is wrong to have this setting on the portal

Should it be in sulu-standard, then? It'll be 100% confusing to users. What can I do with it in my example? Should I change it in any way?

All in all, it seems to me there's a very big curse of knowledge going on in the docs (or I'm just dumb, which is possible :)). Basically, people who understand the ins and outs of Sulu have written the docs, leading to a situation where the docs are only intuitive to those involved with the project, but absolutely confusing to outsiders. I recommend getting an outsider as a developer evangelist (DX guy, essentially), who can not only pick your brains 100% in order to understand everything, but also put this newly acquired knowledge to paper in a newbie-friendly way. It is my opinion that this is essential if Sulu wants to break into end-user space.

Yes, the corporation does publish stuff in Austria, Germany and Switzerland. I have not explained adequately - when I say "X web presence", it means "website in X country", so to speak.

Well, then the nesting like I have explained it would definitely make sense. You'll probably need separate languages for each country anyway, since in many cases there are different imprint addresses. For all the other pages, where you can reuse the same content for all german speaking countries, you could use the shadow page feature, which offers the possibility to fallback to another language.

Can you give me an example of that? I'm not sure I understand what this means.

This means that if you have configured the URL in the webspace config like acme.ch/{localization} there will only be a redirect, if you access acme.ch to the default language (e.g. acme.ch/de-ch). As said, that has already been under discussion, I think there should be a configuration switch to decide if the content should be published to acme.ch, or if this redirect should happen.

Should it be in sulu-standard, then? It'll be 100% confusing to users. What can I do with it in my example? Should I change it in any way?

What I was trying to say, is that this option should not be located under the <portal> tag, but directly under the webspace tag. But you are right, currently the tree strategy is the only existing one, so this should be the default, and it should not be necessary to have this in the webspace configuration.

@Swader First, let me say a big THANK YOU for your time and effort giving us feedback!

Regarding your last statement about the "curse of knowledge": We are very aware that there is a quite steep learning curve involved when working with Sulu. We do a lot of things very different than other CMS which was basically the main reason for us to develop our own product. Until now out main tasks was to implement the technical parts of the system. Thus the "lack" of documentation, especially when it comes to to the more architectural aspects of the system.

Please be aware that Sulu is still a very young project and we are listening VERY closely to user feedback (such as yours). We have a small but active community. The documentation has been updated dramatically in the last 3 months based on user requests and we are hard working on more content.

I fully support you when you say that we need an outside view when we talk about the system. So again, feedback as yours is vey much appreciated and will lead to much more helpful docs.

@Swader Do you have any questions left, or can we close this issue?

Let me pick your brain at WebSummerCamp and then I'll respond here :)

Ok, sounds like a good solution :) Just thought it might be a good idea to ping once more, since issue is almost a year old.

sulu / sulu-standard

Please verify my example of an international corporation webspace #555

International Corporation

Localizations

URLs

Resource Locator Strategy