Apostrophe 3.3.0: Localization is here! 🎊

[agilbert]

Hi everyone,

Today we are very pleased to share our first release of Apostrophe's new localization tools. This is the result of several weeks of design and development and was influenced heavily by feedback from the community along with some major support and collaboration with our partners at Michelin. It's a big release, and the best place to dive in is right in our new docs for these features. We hope you take a moment to check those out, but for right now here are some notable highlights:

• You can now configure your site so all of your content is editable across multiple locales.
• You can also now localize static templates in your Apostrophe projects, as well as all of Apostrophe's core UI components.
• Everything works without needing to install a new module, simply upgrade to Apostrophe 3.3 and configure the locales for your project.

For a quick example of the content localization features check out this video below.

Bonjour.le.monde.mov

In the days ahead, we will be updating our public demo to show off some specific multi-locale configurations. For now, the best way to try out these tools yourself is to update your project to 3.3 and follow the documentation to set up some locales.

This is a huge step forward for A3 and we think it is a big improvement over the experience of localizing content in A2. We are really excited to get this out there, and looking forward to feedback from the community. Please don't hesitate to open any new issues on GitHub with any specific questions, suggestions, or bug reports. Also, please do reach out to us if you'd like to contribute some translations of the Apostrophe UI.

As always, read on for the full details from this latest release:

Apostrophe 3.3.0

Fixes

• Addresses the page jump when using the in-context undo/redo feature. The page will immediately return users to their origin scroll position after the content refreshes.
• Resolves slug-related bug when switching between images in the archived view of the media manager. The slug field was not taking into account the double slug prefix case.
• Fixes migration task crash when parking new page. Thanks to Miro Yovchev for this fix.
• Fixes incorrect month name in AposCellDate, which can be optionally used in manage views of pieces. Thanks to Miro Yovchev for this fix.

Adds

• This version achieves localization (l10n) through a rich set of internationalization (i18n) features. For more information, see the documentation.
• There is support for both static string localization and dynamic content localization.
• The home page, other parked pages, and the global document are automatically replicated to all configured locales at startup. Parked properties are refreshed if needed. Other pages and pieces are replicated if and when an editor chooses to do so.
• An API route has been added for voluntary replication, i.e. when deciding a document should exist in a second locale, or desiring to overwrite the current draft contents in locale B with the draft contents of locale A.
• Locales can specify prefix and hostname options, which are automatically recognized by middleware that removes the prefix dynamically where appropriate and sets req.locale. In 3.x this works more like the global site prefix option. This is a departure from 2.x which stored the prefix directly in the slug, creating maintenance issues.
• Locales are stateless: they are never recorded in the session. This eliminates many avenues for bugs and bad SEO. However, this also means the developer must fully distinguish them from the beginning via either prefix or hostname. A helpful error message is displayed if this is not the case.
• Switching locales preserves the user's editing session even if on separate hostnames. To enable this, if any locales have hostnames, all configured locales must have hostnames and/or baseUrl must be set for those that don't.
• An API route has been added to discover the locales in which a document exists. This provides basic information only for performance (it does not report title or _url).
• Editors can "localize" documents, copying draft content from one locale to another to create a corresponding document in a different locale. For convenience related documents, such as images and other pieces directly referenced by the document's structure, can be localized at the same time. Developers can opt out of this mechanism for a piece type entirely, check the box by default for that type, or leave it as an "opt-in" choice.
• The @apostrophecms/i18n module now uses i18next to implement static localization. All phrases in the Vue-based admin UI are passed through i18next via this.$t, and i18next is also available via req.t() in routes and __t() in templates. Apostrophe's own admin UI phrases are in the apostrophe namespace for a clean separation. An array of locale codes, such as en or fr or en-au, can be specified using the locales option to the @apostrophecms/i18n module. The first locale is the default, unless the defaultLocale option is set. If no locales are set, the locale defaults to en. The i18next-http-middleware locale guesser is installed and will select an available locale if possible, otherwise it will fall back to the default.
• In the admin UI, v-tooltip has been extended as v-apos-tooltip, which passes phrases through i18next.
• Developers can link to alternate locales by iterating over data.localizations in any page template. Each element always has locale, label and homePageUrl properties. Each element also has an available property (if true, the current context document is available in that locale), title and a small number of other document properties are populated, and _url redirects to the context document in that locale. The current locale is marked with current: true.
• To facilitate adding interpolated values to phrases that are passed as a single value through many layers of code, the this.$t helper provided in Vue also accepts an object argument with a key property. Additional properties may be used for interpolation.
• i18next localization JSON files can be added to the i18n subdirectory of any module, as long as its i18n option is set. The i18n object may specify ns to give an i18next namespace, otherwise phrases are in the default namespace, used when no namespace is specified with a : in an i18next call. The default namespace is yours for use at project level. Multiple modules may contribute to the same namespace.
• If APOS_DEBUG_I18N=1 is set in the environment, the i18next debug flag is activated. For server-side translations, i.e. req.t() and __t(), debugging output will appear on the server console. For browser-side translations in the Vue admin UI, debugging output will appear in the browser console.
• If APOS_SHOW_I18N=1 is set in the environment, all phrases passed through i18next are visually marked, to make it easier to find those that didn't go through i18next. This does not mean translations actually exist in the JSON files. For that, review the output of APOS_DEBUG_I18N=1.
• There is a locale switcher for editors.
• There is a backend route to accept a new locale on switch.
• A req.clone(properties) method is now available. This creates a clone of the req object, optionally passing in an object of properties to be set. The use of req.clone ensures the new object supports req.get and other methods of a true req object. This technique is mainly used to obtain a new request object with the same privileges but a different mode or locale, i.e. mode: 'published'.
• Fallback wrappers are provided for the req.__(), res.__() and __() localization helpers, which were never official or documented in 3.x but may be in use in projects ported from 2.x. These wrappers do not localize but do output the input they are given along with a developer warning. You should migrate them to use req.t() (in server-side javascript) or __t() (Nunjucks templates).

Changes

• Bolsters the CSS that backs Apostrophe UI's typography to help prevent unintended style leaks at project-level code.
• Removes the 2.x series changelog entries. They can be found in the 2.0 branch in Github.

Apostrophe 3.x extensions

redirect 3.0.1

• Localization is inappropriate for redirects since it's necessary to be able to redirect from any URL. Previously autopublish: true was used by the module, but localize: false is more appropriate as it eliminates multiple locale versions altogether. A migration has been added to take care of existing redirects in this transition.
• Fixes README code examples for the withType and statusCode options.

Apostrophe 2.220.5

• The template error page was returning a 200 status code. It now correctly returns a 500 status code.

Apostrophe 2.x extensions

apostrophe-forms 1.10.4

• Use self.getOption to fetch the recaptcha options for full compatibility with apostrophe-override-options.

apostrophe-security-headers 1.0.1

• The headers Referrer-Policy, X-Content-Type-Options and Permissions-Policy were inadvertently left off a list that allows them to be configured. The default values for the first two are now as was always intended. The third is not enabled by default but can now optionally be configured.

apostrophe-workflow 2.39.4

• When fetching the live version of a document for comparison, do so using the appropriate manager module, so that all cursor filters for that type are consulted. Thanks to Michelin for their support of this work.

Other modules

moog-require 1.3.1

• Apostrophe will no longer attempt to load a module from npm that happens to have the same name as a configured Apostrophe module in app.js, unless it is an explicit dependency of the project itself. This corrects a flaw where a transitive dependency of a submodule could be mistakenly loaded, leading to a crash.

[doup]

Hi! I've been testing this and I've few doubts/suggestions, sorry if the nomenclature is a little bit off, it's been a while since I read the docs. Here it goes:

Is it possible to force all the locales to have a prefix?

Maybe it's a matter of taste, but I usually prefer to have all the locales prefixed and redirect to the default one when entering the root path /. Alternatively, the root / path could show a custom page with links to different locales.

Is it possible to define non-localizable fields?

The idea here is to ease the translation process and keep consistency. So all the locales might share the same image, but the text should be translated. The minimum for me would be to allow this per field. The non-localizable fields could be edited from any locale.

The ideal for me would be that also the areas, like the one in @apostrophecms/home-page could support this. So the area widgets reordering is reflected between locales, and image/video fields are kept in sync, but the rich-text one can be translated. This should be configurable.

Similarly, the array fields should be able to keep in sync. Imagine a Project which has some links array. Assuming these only contain the URL (so there is nothing to localize), these should be kept in sync between locales. Otherwise it's a maintenance burden for the CMS user.

I understand this might be a pain in the ass to implement, but anything in this direction for me it's really appreciated. If this is possible some kind of indicator in the i18n fields would be helpful (see next section screenshot), e.g.:

Switch between locales in Edit modal

In the Edit modal it would be very useful to switch rapidly between locales. Something similar to what is done in Bolt:

---

Thanks!

[boutell]

Thanks for these suggestions! We do already plan to support locale switching inside the modal at some point, as long as it's the top modal. We wanted to do it right away, but it's a bit tricky and we didn't want to introduce bugs on the first release of localization. Re: having some non-localized fields, that is an interesting idea. I see why it could be valuable, it could prevent translators from making changes that are actually not a good idea to fields that should be left alone. However if we let them be edited from any locale as you suggest, that would negate some of the benefit by allowing the translator for Portuguese to make a change that would impact all locales, possibly without even knowing it. So it's tough to say what the best policy really is. Something to think about. I suggest that you submit it on our product board: https://portal.productboard.com/apostrophecms/1-product-roadmap/tabs/1-under-consideration As for forcing all locales to have a prefix, you have a good point about that too. One easy workaround for now would be to redirect in browser javascript. Right now (peeps at the middleware) it would be a bit of a pain to do it at project level server side, which we should look at.

…

On Wed, Sep 8, 2021 at 3:26 AM Asier Illarramendi ***@***.***> wrote: Hi! I've been testing this and I've few doubts/suggestions, sorry if the nomenclature is a little bit off, it's been a while since I read the docs. Here it goes: Is it possible to force all the locales to have a prefix? Maybe it's a matter of taste, but I usually prefer to have all the locales prefixed and redirect to the default one when entering the root path /. Alternatively, the root / path could show a custom page with links to different locales. Is it possible to define non-localizable fields? The idea here is to ease the translation process and keep consistency. So all the locales might share the same image, but the text should be translated. The minimum for me would be to allow this per field. The non-localizable fields could be edited from any locale. The ideal for me would be that also the areas, like the one in @apostrophecms/home-page could support this. So the area widgets reordering is reflected between locales, and image/video fields are kept in sync, but the rich-text one can be translated. This should be configurable. Similarly, the array fields should be able to keep in sync. Imagine a *Project* which has some *links* array. Assuming these only contain the URL (so there is nothing to localize), these should be kept in sync between locales. Otherwise it's a maintenance burden for the CMS user. I understand this might be a pain in the ass to implement, but anything in this direction for me it's really appreciated. If this is possible some kind of indicator in the i18n fields would be helpful (see next section screenshot), e.g.: [image: image] <https://user-images.githubusercontent.com/188612/132462103-1dcdedbe-50f3-421f-84cf-605319601819.png> Switch between locales in Edit modal In the Edit modal it would be very useful to switch rapidly between locales. Something similar to what is done in Bolt: [image: image] <https://user-images.githubusercontent.com/188612/132461917-bed97d0a-f0cc-4a1c-b709-e3cc68c8dea9.png> ------------------------------ Thanks! — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#3375 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAH27INBEBR3T67OSSUWQLUA4FZ7ANCNFSM5DCNKDRA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

-- THOMAS BOUTELL | CHIEF TECHNOLOGY OFFICER APOSTROPHECMS | apostrophecms.com | he/him/his