Our internal, server-side i18n package is deprecated, and so is the use of i18n.t().

Instead we have a new package @tryghost/tpl that does string interpolation and makes refactoring i18n out of the codebase easier.



We have successfully removed i18n.t() from core/frontend, but the rest of the codebase has many many references that need to be updated. At the time of writing there are 404 instances of i18n.t in 143 files!

Steps to refactor

A reference refactor commit can be found here: ca149f2

1. Wherever there's an instance of i18n.t in a file we need to:

Replace
const i18n.t = require('../[some nesting]../core/shared/i18n)

With

const tpl = require('@tryghost/tpl');

2. Then at the top of the document, after the last require, add a new messages object:

const messages = {
};

That's the setup done for this file.

3. For each instance of i18n.t() for example:

i18n.t('common.warnings.helpers.flagMustBeEnabled', {flagName: 'something'});

You'll need to go into core/shared/i18n/translations/en.json and find the correct string.

E.g
common.warnings.helpers.flagMustBeEnabled

Will look like:
"flagMustBeEnabled": "The {flagName} flag must be enabled in labs if you wish to use the \\{\\{{helperName}\\}\\} helper.",

Copy this string into your messages object, as is. If you have your editor setup to use our eslint rules & set to auto fix or auto fix on save, it should automatically fix the quotes & commas.

⚠️ Don't cut or otherwise remove the string from en.json. Strings are reused in multiple places, and it's a waste of time trying to figure out if a string is now unused. We'll simply delete the file verbatim once this refactor is finished.

You should now have something like this:

const tpl = require('@tryghost/tpl');
// more requires

const messages = {
	flagMustBeEnabled: 'The {flagName} flag must be enabled in labs if you wish to use the \\{\\{{helperName}\\}\\} helper.'
};

Finally, you need to change the reference to i18n.t to tpl and the string path, to the messages variable:

So from:

i18n.t('common.warnings.helpers.flagMustBeEnabled', {flagName: 'something'});

To:

tpl(messages.flagMustBeEnabled, {flagName: 'something'});

And that's it!

There is no need to mess with the escaping or interpolation!

Check your work!

To make sure you've not broken anything & followed our code standard, run yarn test:all.

You can also use yarn lint to double check on quotes, commas and other pesky problems that will fail the build. Again, having your editor set to autofix EsLint errors will prevent this being a problem.

How to work on this issue

The slow and steady approach to refactoring is the only thing that really works. Branches should be very short lived (<1 day if possible). Therefore, please do not attempt to do this entire refactor in a single PR. It is not possible for us to review!

Instead, please find a single file with many references, or a small subfolder of the codebase with a handful of usages, make the changes, and submit a PR. Then repeat.

Please follow our contribution guidelines as closely as you can, particularly being sure to reference this issue in your commit. Refactor commits should not use emojis as they are not user-facing changes.

Note: This refactor has almost no user facing impact and no tests should break or change. The en.json file should also not change as a result of this work.

A reference refactor commit can be found here: ca149f2

Thank you 🙏 ❤️ 🙏

Why is i18n.t deprecated?

💡 Removing this does not at all impact the current or future ability to translate Ghost.

This was a concept introduced years ago with a view to aiding translating Ghost. Most people are looking to either translate their theme (not affected by this refactor) or have a translated Ghost Admin panel, which is not solved by this utility. Most people are not interested in translating errors from the theme or JSON APIs, which is effectively what this util would do if we allowed alternative translation files. Meanwhile, this utility creates tight coupling throughout the Ghost codebase which is slowing us down and preventing us from shipping things we do want.