PRO-8154: Strip Latin accents #5137

myovchev · 2025-11-04T16:35:00Z

Summary

Introduce a configurable option stripUrlAccents in the @apostrophecms/i18n module to control whether Latin accents are stripped from URLs (slugs) and attachment names.

Default remains unchanged: accents are preserved in slugs (backward compatible).
When @apostrophecms/i18n.options.stripUrlAccents is true:
- New/updated document slugs (pages, pieces, slug fields) have accents removed.
- Attachment name values are normalized without accents on upload.
- The admin UI slug input reflects accent-stripping in real time.
A new task @apostrophecms/i18n:strip-slug-accents is provided to update existing document slugs and attachment names when adopting this option.

What are the specific steps to test this change?

Default behavior (accents preserved)

Ensure stripUrlAccents is absent or set to false in @apostrophecms/i18n options.
Create a page and a piece titled: C'est déjà l'été.
Expected slugs:
- Piece: c-est-déjà-l-été
- Page: /c-est-déjà-l-été
Upload an attachment named: été-image.png
- Expected stored name in database (aposAttachments collection): été-image

Enable accent stripping for new/updated content

Set @apostrophecms/i18n.options.stripUrlAccents = true.
Create a new page and piece:
- Title: C'est déjà l'été
- Expected slugs:
  - Piece: c-est-deja-l-ete
  - Page: /c-est-deja-l-ete
Upload an attachment named: été-image.png
- Expected stored name in database (aposAttachments collection): ete-image
In the admin UI, type an accented title and observe the slug field: it should show accent-free characters.

Migrate existing content (optional when adopting the option)

With stripUrlAccents: true, run the task:
- node app @apostrophecms/i18n:strip-slug-accents
Expected:
- Existing slugs like /c-est-déjà-l-été become /c-est-deja-l-ete.
- Attachment names like été-image become ete-image.
- Task logs counts of updated documents and attachments.

Notes

The option only affects new/updated content unless the task is run.
Non-Latin scripts (e.g., Cyrillic) continue to be handled by sluggo; the deburring only affects Latin accent marks.

What kind of change does this PR introduce?

(Check at least one)

Make sure the PR fulfills these requirements:

It includes a) the existing issue ID being resolved, b) a convincing reason for adding this feature, or c) a clear description of the bug it resolves
The changelog is updated
Related documentation has been updated
Related tests have been updated

If adding a new feature without an already open issue, it's best to open a feature request issue first and wait for approval before working on it.

Other information:

…ttachment names

linear · 2025-11-04T16:35:03Z

PRO-8154 As a developer I should be able to prevent accent marks from appearing in slugs

modules/@apostrophecms/doc/index.js

modules/@apostrophecms/i18n/index.js

haroun · 2025-11-06T09:31:52Z

modules/@apostrophecms/i18n/index.js

+          await self.apos.migration.eachDoc({}, 5, async doc => {
+            const slug = doc.slug;
+            const req = self.apos.task.getAdminReq({
+              locale: doc.aposLocale?.split(':')[0] || 'en'


Forcing the locale to en seems wrong. We have i18n defaultLocale for that.
If you're using doc.aposLocale you can also pass it as query: { aposLocale: doc.aposLocale } and let the i18n middleware do its magic.

aposLocale can be undefined. I'll switch to default locale though.

modules/@apostrophecms/i18n/index.js

haroun · 2025-11-06T09:44:04Z

modules/@apostrophecms/page-type/index.js

      // If the page does not yet have a slug, add one based on the
      // title; throw an error if there is no title
-      ensureSlug(page) {
+      ensureSlug(page, { stripAccents } = {}) {


I don't think this scales well. We should work towards ensureSlug and slugify keeping the same signature somehow and fetching the stripAccents from the i18n locales option in my opinion. If we don't do that, it means that we have to change multiple external/pro modules to support the new feature, and apostrophe users will have to do the same. There will always be a piece of code somewhere where stripAccents is not passed and it will lead to inconsistent behavior that will be hard to track.

ensureSlug is internal method. It's called internally via event.
Utils should not fetch/know what i18n options are, so slugify is what it is - an util with an option.
Having an option for ensureSlug is a clear contract. This is not a public API so no BC is required.

I reverted option per locale because of many and bad showstoppers. I explained above that the there was an agreement to go with the simple "rule them all" option.

haroun · 2025-11-06T09:47:01Z

modules/@apostrophecms/util/index.js

      slugify(s, options) {
-        return require('sluggo')(s, options);
+        const { stripAccents, ...opts } = options || {};
+        const slug = require('sluggo')(s, opts);


We should put that require statement at the top.

Is the order of operations important here? slugify then strip accents vs strip accents then slugify.

Moving the require is out of context for this PR. (Many other utils does it).
The current order of operation makes sense. You don't want to change the behavior of sluggo with pre-filtering the input, but to filter the output of the sluggo.

haroun · 2025-11-06T09:49:57Z

modules/@apostrophecms/util/index.js

+      // set options.stripAccents to true.
      slugify(s, options) {
-        return require('sluggo')(s, options);
+        const { stripAccents, ...opts } = options || {};


This new option is a challenge because we need to update all the usages of the slugify method, in our modules but our clients needs to do the same. There is a default value, but this is some kind of a breaking change, mainly because it requires changes to the code for the behavior to remain consistent.

The accent cleaning behavior can't break BC because it's a new feature. This code is fully BC.

haroun · 2025-11-06T09:50:54Z

modules/@apostrophecms/schema/ui/apos/logic/AposInputSlug.js

      return this.field.page && apos.i18n.locales[apos.i18n.locale].prefix;
+    },
+    stripAccents() {
+      return apos.i18n.stripUrlAccents === true;


Having this here will make it difficult to have this feature enabled/disabled per locales.

This is one of the main showstoppers for per locale feature, which we don't implement with the current PR.

Co-authored-by: haroun <[email protected]>

… into PRO-8154-accent

myovchev · 2025-11-06T14:53:54Z

@haroun Added a patch to address the problems

in the task, only accents are removed/compared, no double slugify is attempted; it should solve the problems
in the task, switched to the default language
in the task, we use manager to update the doc now, so that the URL redirects are recorded.

Add stripUrlAccents option to control accent stripping in slugs and a…

537dd1a

…ttachment names

myovchev added 2 commits November 5, 2025 10:37

Test deduplciation

a2c5a4e

Fix changelog

8aa5d8c

myovchev requested a review from haroun November 5, 2025 08:40

haroun requested changes Nov 6, 2025

View reviewed changes

myovchev and others added 3 commits November 6, 2025 15:58

Update modules/@apostrophecms/doc/index.js

9f3ad2f

Co-authored-by: haroun <[email protected]>

Fix task to use default locale and deburr instead of double slugify.

bfd97a8

Merge branch 'PRO-8154-accent' of github.com:apostrophecms/apostrophe…

3f48b5b

… into PRO-8154-accent

myovchev requested a review from haroun November 6, 2025 14:37

Refactor slugify calls to remove stripAccents option for consistency

5e81886

myovchev mentioned this pull request Nov 6, 2025

PRO-8580: Add stripAccents support to slugify helper apostrophecms/apostrophe-astro#58

Open

10 tasks

PRO-8154: Strip Latin accents #5137

Are you sure you want to change the base?

PRO-8154: Strip Latin accents #5137

Uh oh!

Conversation

myovchev commented Nov 4, 2025

Summary

Summary

What are the specific steps to test this change?

What kind of change does this PR introduce?

Make sure the PR fulfills these requirements:

Uh oh!

linear bot commented Nov 4, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

myovchev Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

myovchev commented Nov 6, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

myovchev Nov 6, 2025 •

edited

Loading