Spike: Best Practices for Creating Multi-Language Secondary Country Websites

[ZoeBeykirch]

Description: Given that we have a new request to establish multi-language Road Choice market sites (https://github.com/hlxsites/vg-roadchoice-com/issues/222), we want to first conduct spike research on best practices for implementing a multi-language market sites that closely mirror the USA parent site. The goal is to gather insights and recommendations that will guide the development team in creating a seamless, on brand experience for all users no matter which market site they are interacting with. Additionally, this research should outline best practices for how our marketing editors should go about making content changes in the USA site that should be applied to the market sites.

[BeckyMedlin]

@ZoeBeykirch Is this limited to Canadian French and Mexican Spanish or are other language variations needed?

[ZoeBeykirch]

The current requirement is only for Canadian French and Mexican Spanish

[mollyaljenkins]

Expected outcome of the spike:

• One or several proposals of the content structure
• Effort estimation for each approach
• Align with the CMS team to choose the best approach from editing perspective
• Align with business to choose the best from cost perspective

Existing pull request

• Syb had a similar solution in the works for MT
• Guide for this solution
• Franklin has existing feature for multi-language

[mollyaljenkins]

When the results of the spike are available - #222 is ready for refinement

[cogniSyb]

Each EDS website will have its own Github repository and folder on SharePoint.

Data stored on Github

• Each Github repository contains configuration for that specific website.
  • fstab.yaml refers to the content endpoint
  • scripts/constants.js contains the site-specific configuration needed in JavaScript. For example, the GTM code
  • GitHub actions/webhooks that require specific paths that differ from the origin or have different language paths can use variables. Example: https://github.com/hlxsites/vg-volvotrucks-us/blob/main/.github/workflows/generate-atom-news-feed.yaml and https://github.com/hlxsites/vg-volvotrucks-us/settings/variables/actions

SharePoint folder structure

• On SharePoint, a multi-language website will have folders in the root containing the locale. Example: Volvo Trucks Canada has folders en-ca and fr-ca
  • Pages with a different language can also be added to a website. Example: https://www.volvotrucks.us/recalls/ versus https://www.volvotrucks.us/fr/recalls/
  • It’s okay to use en instead of en-ca as a folder name, though setting a locale in metadata is preferred (see below)
• Advice for the Mexican Roadchoice website is to set up a folder for Spanish to prevent rework if an English version is added later; also because of the next point.
• Ensure that the navigation is consistent across all site language versions. Users should be able to easily switch between languages without losing their place on the site.

Data stored in placeholders

• Repeated content for UI will reside in the file placeholder.xlsx on SharePoint. It stays in its language folder
• The files should be in sync. If translations are not available, it’s better to have the dominant language available as a fallback
• If needed for development, placeholder content can be retrieved from another language
• Advice is to use the latest version of aem.js for new websites when dealing with placeholders: https://github.com/adobe/aem-boilerplate/blob/main/scripts/aem.js

Data stored in metadata

• All websites should have the correct lang attribute set on the HTML for SEO and accessibility.
  • This should be done in metadata.xlsx
  • It’s preferable to use a locale like en-CA instead of en
  • When using locales, make sure to follow the capitalization structure for consistency and code compatibility
• Feature flags can be set so authors can enable and disable functionality. As this adds code to each HTML page, it’s advised to use this feature sparingly. Example: disable the footer on the page for a truck configurator

URL	locale	disable-footer
/en-ca/**	en-CA
/fr-ca/**	fr-CA
/en-ca/truck-configurator		true
/fr-ca/truck-configurator		true

Handling internationalization and localization

• A redirect is set up for the default language. Example: https://www.volvotrucks.ca/ redirects to https://www.volvotrucks.ca/en-ca/
• Use machine-readable objects as much as possible in the interface to provide support for localization
• Use available JS APIs for marking up dates like DateTimeFormat. Dealing with lists, formatting numbers, and more can also be handled by JS.
• There are other files to consider with multi-language websites:
  • robots.txt
  • sitemap.xml
  • query-index.xlsx

[janedbarra]

With each Github repository containing configuration for that specific website, would we have duplicate website data files for each market? I.e. if Road Choice brakes are offered in CA, US, and MX, we would have 3 separate files for that program? There is a lot of duplication b/t US and CA (right now there are just a few programs that are US only). For MX, I see it being less than 10 product offerings as they start out.

Also love the point of users being able to switch languages w/o losing their space on the site.

Once we begin work on this project, the expectation is to have a CA site (available in English and French), a US site (available in English and Spanish), and a MX site (available in Spanish).

[cogniSyb]

@janedbarra Yes, though we’ll automate the copying of data. You’ll have to update the data only in the folder for .com. The other content (in Word files and the placeholder.xlsx) will need to be updated in the respective folder. The current Excel files will need to be expanded with a column for specifying which market the item belongs to. This way we can filter the data on the country website.

Being able to switch language on the website and can happen. Let me explain the following:

Ensure that the navigation is consistent across all site language versions

The folder structure and documents should maintain the same filenames. They shouldn’t be translated. This allows for easy development/maintenance and authoring.

[janedbarra]

Okay that makes sense, thank you!

[BeckyMedlin]

@cogniSyb @mollyaljenkins Is the status on this item correct?