How to translate Ghost (guide)

Developer help Self-hosting
1

Hi all!

With the help of the docs and this forum I’ve managed to translate everything a (non-admin) user gets to see. It took me a while, so I’m sharing my process in the hope it might help someone out. This only works for self hosted instances. I’m using Ghost v5.15.0.

1. Translate the content
Translate everything possible from the backend (https://yoursite.com/ghost/). Besides posts, pages and tags, don’t forget to also translate fields in the following settings:

  1. Settings > General
  2. Settings > Design
  3. Settings > Navigation
  4. Settings > Membership > Portal Settings
  5. Settings > Email newsletter

2. Translate the theme
Fork/clone the theme you want to use and translate it following the official Ghost docs.

3. Translate the drop-in widgets
There’s three parts left to translate on the actual website:

  1. Portal (login and membership)
  2. Sodo-search (search bar)
  3. Comments-ui (comments, only necessary if you enable them)

Luckily the process is very similar for these three:

  1. Fork/clone the repo (linked above)
  2. Run yarn to install
  3. Make your translations (and any other adjustments)
  4. Run yarn build *
  5. Copy the output from /umd to your theme: (cp <widget>/umd/portal.min.js <your-theme>/assets/js/portal.min.js)
  6. Change the url of the widget in the Ghost config file**
  7. Run GScan
  8. Include the theme in your Ghost instance (for instance by running yarn zip and uploading the theme in the backend, or use the GitHub Actions integration)
  9. Restart ghost

*For Portal yarn build (step 4) worked right away, but sodo-search and comments-ui complained about a missing file: ./public/main.css. I removed the snippet below from the scripts/build-combined.js files. If anyone could tell me why this happens and/or has a less hacky solution, please let me know!

fs.copyFile('./public/main.css', './umd/main.css', (err) => {
    if (err) {
        throw err;
    }
});

**This is how I included the widgets in the config.production.json (step 6):

"portal": {
    "url": "/assets/js/portal.min.js"
},

"sodoSearch": {
    "url": "/assets/js/sodo-search.min.js"
},

"comments": {
    "url": "/assets/js/comments-ui.min.js"
}

Here’s a list of files where I had to make translations:

Portal:

src/actions.js
src/components/Notification.js
src/components/common/BackButton.js
src/components/common/NewsletterManagement.js
src/components/common/PoweredBy.js
src/components/pages/AccountHomePage.js
src/components/pages/AccountProfilePage.js
src/components/pages/MagicLinkPage.js
src/components/pages/NewsletterSelectionPage.js
src/components/pages/OfferPage.js
src/components/pages/SigninPage.js
src/components/pages/SigninPage.test.js
src/components/pages/SignupPage.js
src/utils/api.js
src/utils/fixtures-generator.js
src/utils/fixtures.js
src/utils/form.js

Sodo-search:

src/components/PopupModal.js

Comments-ui:

scripts/build-combined.js
src/components/content/Avatar.js
src/components/content/CTABox.js
src/components/content/Comment.js
src/components/content/Pagination.js
src/components/content/buttons/ReplyButton.js
src/components/content/context-menus/AuthorContextMenu.js
src/components/content/context-menus/NotAuthorContextMenu.js
src/components/content/forms/EditForm.js
src/components/content/forms/Form.js
src/components/content/forms/MainForm.js
src/components/content/forms/ReplyForm.js
src/components/popups/AddDetailsPopup.js
src/components/popups/ReportPopup.js
src/utils/helpers.js

Whenever new versions of portal/search/comments are released, you can run git pull, resolve conflicts and repeat steps 5, 7, 8 and 9.

4. Translate the email templates
This is the only part where we have to change the actual Ghost core. Download the following files from your Ghost instance:

  • Transactional emails:
    /current/core/server/services/members/emails/*.js
    /current/core/server/services/members/api.js
  • New post email (to translate the “unsubscribe” text in the footer):
    /current/core/server/services/mega/template.js

Edit them, and upload them to your server to overwrite the originals. If your temporarily change the extension to .html it’s a lot easier to see what needs to be translated (either in the browser or with syntax highlighting in your IDE). Mind that these files will be overwritten every time you upgrade Ghost.

All done! :rocket:

2 Likes
2

Hi ! Thank you for sharing this. Do you know that it is planned by Ghost team ?

https://forum.ghost.org/t/portal-and-email-component-translations/19144/10

3

I did not, thanks for pointing that out! Consider this a temporary workaround :slight_smile: