Adding translations

This is an experimental feature and should not be used in production without testing. You can enable it by enabling the site setting multilingual enable custom translations

You can use the Multilingual Plugin to add translations to your Discourse. You can currently add three types of translations:

  • Interface
  • Category Name or Description
  • Tag

You can see examples of each type of translation here: Open the link in an incognito window and select “Warlpiri” (for the language of the Warlpiri people).

To add any translation you first have to have an entry for the language of the translations in your Languages list. If there is not currently a language in that list for your translation, you can add one:

File format

All translations need to be uploaded as a .yml file. The format depends on the type of translation you’re uploading

Interface (“locales”)

Interface translations follow the same format as locale files in Discourse:



   admin_js: #(optional)

   wizard_js: #(optional)



In example screenshot (above)


        title: "karlirr-kari"
        title: "mintirlpari"
        title: "waji-nyanyi"
      create: "yirrarni"

Category name or description

Category name and description translations use category slugs as keys, using key nesting to represent parent-child relationships, e.g.




slug: translated name
   slug: translated child name

If you want to translate both parents and children in a parent-child category hierarchy, use _ as the key for the parent translation, i.e.

slug: translated name
   _: translated parent name
   slug: translated child name

In example screenshot (above)


welcome: pardu-pardu-mani
clients: kalyardi
  _: milya-pinyi
  clients: kalyardi milya-pinyi



tag: translated tag

In example screenshot (above)


pavilion: parnka
follow: ngurra

Any idea what is wrong with my yaml syntax here? The parent is being translated but not the children

  _: Críticas - Imagens
  avian-critiques: Críticas - Aves
  flora-critiques: Críticas - Flora
  human-fauna-critiques: Críticas - Humanos e Fauna
  landscpae-critiques: Críticas - Paisagem
  macro-critiques: Críticas - Macro
  non-nature-critiques: Críticas - Não Natureza
  wildlife-critiques: Críticas - Vida Selvagem
  weekly-challenge: Desafio semanal

I suspect the issue is that you need to use quotes for the translations

  _: "Críticas - Imagens"
  avian-critiques: "Críticas - Aves"

However, there’s a bigger issue with translations. They’re not persisting between updates to the forum. I’ll need to fix that first then come back to this.

Thanks, but that did not work either. No rush on this!

very very thanks angus, it works for me
the subcategory is also work @davidkingham, you can have a try again.

Hi, are the experimental translation currently working? I tried to upload a file but nothing happened. I couldn’t see any changes nor any new translation row.


yml file i tried:

yml combinations i tried:

novedades: "news"
    _: "news"
novedades: news

@NicoIzquierdo This feature is being worked on currently, including some fixes. These will be complete by the end of June.

cc @merefield

This should all be working now, and better yet:

  • we now support translation of Category descriptions
  • uploads are now persistent across rebuilds

… but please report any issues.

I tried to add some unsupported languages (Georgian, Uzbekistani, Kazakh…) to translate the interface.
I created the file client.code.yaml as a copy of this one (just updated the file name and the first line according to the language code - ka, uz, kk, …):
discourse/client.en.yml at main · discourse/discourse · GitHub
Trying to upload the file I get the error “closed stream” or “stream closed in another thread”.

I recorded the following video where I try to upload a whole Kazakh file (I get the error mentioned above) and then a thined out Georgian file (I can upload the file but the translation is not properly shown and working):

@merefield can you please suggest?

@merefield @angus do you have any clue about this problem? sorry to bother but we are stuck and we could use some suggestion

Oh sorry missed this mention. I believe it’s something to do with the core uploader and not with our use case specifically. I’ve raised this with the author but haven’t heard back, i’ll chase.

It happens to me occasionally but works after a retry. Is this happening every time?

Thank you @merefield
Yes, it happens every time. We tried for days and even now we face the same issue

This is a huge file!! I’m not sure I’d expect your strategy to work as this scale has not been specified or tested. There is currently no test case which covers this.

Things might be timing out … you have definitely less than 30 seconds before this will time out on a vanilla install I believe.

  • Can you start with a much smaller file with fewer translations focussing on high priority translations for eg end users only not admin? Focus on the translations you’ve actually done and really need. There is no point in loading the others as these are all loading as overrides and system should in any case use the default language if you’ve not added a translation.

  • You can split it into pieces (each file will need to have same name though so store in different directories)? We could probably improve this option with funding to allow for named subsets. PR welcome.

OK I escalated this to the author of the library at the Discourse team and he’s going to have a look at this this week and give me his opinion.

In the meantime I noticed something interesting:

  • If you upload a small file and keep trying it eventually works, then if you repeat this it works every time?

So I suggest trying to load a small file and repeat until it works, and then upload a bigger file.

Thank you @merefield. As per your suggestion I splitted a mkclient file (including only the main js section) into 5 smaller files. They have been properly uploaded and now in the Translations area I have 5 mk client files listed (is this correct?).

Now I was expecting to find македонски јазик among the user preferences interface languages, but it is not there. Am I missing any step?

I believe you may still have to load the Custom Language as well with same code.

Apologies for the delay in response. Since this website moved domain my notifications haven’t been on.

@merefield don’t worry and thank you for supporting.

mk was already listed among the Multilingual languages:
Schermata 2022-09-27 alle 12.58.24

By the way I uploaded the mk custom language and nothing changed: it is still listed with no translations.
The only thing that changed is that now I cannot remove the mk client files: I get a “500 error” (even if I remove the upload custom mk language)

You are getting error 500 when trying to delete one of the custom translation files which previously successfully loaded?

Did you see evidence of the translations in overrides in customize → text?

Can you share the full error message AND stack trace in /logs?

Yes, I uploaded the mk client files (5 small files) and when I try to remove them I get the following error:
Schermata 2022-09-27 alle 14.28.33
I have the same issue also with a kk client file I previously used.
Other client files are not affected.

These are the errors in the log:
Schermata 2022-09-27 alle 14.30.28
(if you need further details please authorize the upload of zip files).

customize → text: if I flag “Only show overridden” nothing is displayed.

Thanks, I’ll take a look when I can.