feat: Multilingual YAML file

[tytyvillus]

Description

Currently, it's possible to localise a CV by specifying a language in the locale heading. This is great! But if I want to translate my CV to, say, French, I have to create an entirely seperate YAML file with all the text content translated to French. This becomes annoying once I need to maintain two separate versions of my CV in two different files, and need to go hunt down the correct entry in both if I want to update it.

Possible Solution

A way around this is to allow users to specify different localisation strings for entries using ISO codes. An example of how this might be implemented is the pandoc-localise-yaml filter (full disclosure: written by me), which does it for Pandoc.

Perhaps this is a bit of a niche case, but I can imagine it being useful for at least some users.

Acceptance Criteria

Users should be able to specify several strings for an entry, which can be automatically selected based on the language locale.

To-do list

• ??

[xiaohanyu]

Hello, thanks for raising this.

My understanding, you want something like this:

content:
  basics:
    name: Andy Dufresne
    headline: 
      en: Headed for the Pacific
      fr: En route vers le Pacifique
    phone: "(213) 555-9876"
    email: hi@ppresume.com

For fields that has potential translations (headline, summary, name, etc.), it can accept both an raw string or a Dict<languageCode, string> as the value, and your expect that yamlresume can filter and generate copies of yamls based on the locale.language.

This is doable but with very high pricing:

1. not all fields is translable, for example, email, phone, url etc
2. yamlresume's schema validation is based on the fact that every leaf node of the yaml file is a key: value pair, with most value as the string type, if we change the value to be a Dict<languageCode: string>, then the whole implementation would be revised, it will bloat the JSON schema file drastically as well
3. error handling difficulty:

• what happens if headline has en and fr translations, while name has en and es translations? how to make sure that the number of en translations is equal to the number of fr translations? If they are not equal, then we need some kind of fallback rules (for example, for missing translations, we fallback to en translation or the raw string, but that doesn't make too much sense because en, fr and es are different languages)
• locale.language can specify one value, that being said, when compiling this file, we need to filter out the value based on locale.language. If we want to get all translations, then I guess we have to add a new fields like locale.languages: ['en', 'es', 'fr'], then iterate over locale.languages, but this still raised the question, what if some field is lacking the translations?

---

With all above concerns, I would highly not like to implement this feature unless there are some simple ways for the implementation.

To solve your issue, I can think about two ways:

1. Adopt some LLM with some prompting to translate and sync the changes between different yamlresume copies with different languages, a potential useful repo for this: https://github.com/zhiweio/resume-as-code
2. Inspired by i18n implementation from many web frameworks, we use some kind of placeholders like t('basics.name'), t('basics.headline'), combined with additional JSON translation files, then use some postprocessing script to render these two to a valid yamlresume file, then call yamlresume to build the resume.

i.e:

The yamlresume file resume.yml:

content:
  basics:
    name: Andy Dufresne
    headline: t('basics.headline')
    phone: "(213) 555-9876"
    email: hi@ppresume.com

en translations en.json:

{
  "basics.headline": "Headed for the Pacific"
}

fr translations 'fr.json':

{
  "basics.headline": "En route vers le Pacifique"
}

Then use some script to deal with resume.yml + en.json and resume.yml + fr.json, then use yamlresume to build.

---

Thoughts?

[tytyvillus]

Hi!

Yes, that's exactly what I had in mind. Some thoughts:

1. I agree that not all fields are translateable, but this depends heavily on the user's use case: for example, a user might like to use www.url.com/en in their English-language CV and www.url.com/zh in the Chinese version. This suggests that you shouldn't determine ahead of time which fields are translateable: all fields should get this option.

2. I had not thought of the schema validation feature. I am not sure whether my suggestion can be implemented in that context.

3. I don't think this has any responsibility to fail intelligently. In particular, I think it's fine for locale.language only to take one value and for the validation only to throw an error if that value isn't present in a translation dictionary. This corresponds to users adding translations only as needed: but it's easy for translations to be added because the string to translate is right there.

   For example, if you have

   content:
     basics:
       name: Andy Dufresne
       headline: 
         en: Headed for the Pacific
       phone: "(213) 555-9876"
       email: hi@ppresume.com
   locale:
     language: fr

   you should throw an error saying: content.basics.headline does not have a fr translation. Maybe it helps to define a special key multilingual or translateable, so that an error is thrown whenever multilingual.fr (or whatever the language may be) doesn't exist.

   Then the entry might look like

   content:
     basics:
       name: Andy Dufresne
       headline: 
         multi:
           en: Headed for the Pacific
       phone: 
         multi:
           en: "(213) 555-9876"
           fr: "+1 213 555 98 76"
       email: hi@ppresume.com
   locale:
     language: fr

The way to do this in the JSON scheme, as far as I can tell, would be to have every value be either of type value or a dictionary containing $locale.language: value. I'm not acquainted with JSON schemes — can this be done without bloating? Perhaps inserting the type alternative val | dict{ $locale.language: val} programmatically?

---

As far as regards the proposed solution,

1. could be a viable solution, if the user is willing to trust/use an LLM tool;

2. goes against the main advantage of this proposal, which is to keep separate translations together so that the user can easily cross-reference them.

---

This suggestions is a fairly niche use-case, so I don't think you should bloat your code just to implement it, but if there is a way to implement it efficiently then I think it could prove very useful to a small minority of users.

[AleixMT]

I would also be interested in multilingual support.

[AleixMT]

In my opinion being able to implement something like the proposed:

Perhaps inserting the type alternative val | dict{ $locale.language: val} programmatically?

Seems like the perfect solution: Does not break compatibility and does not bloat the resumees while still providing multilingual support.

[xiaohanyu]

@tytyvillus @AleixMT

JSON schema support the OR check (aka, the union type) like: val | dict{ $locale.language: val}.

But still this will make it hard to revise the locale top key in the current design, i.e, locale.language now should support arrays as well.

And

content:
  basics:
    name: Andy Dufresne
    headline: 
      multi:
        en: Headed for the Pacific
    phone: 
      multi:
        en: "(213) 555-9876"
        fr: "+1 213 555 98 76"
    email: hi@ppresume.com

Sounds like a good approach because it makes thing more explicit.

Any way for me I still prefer to keep the the core lib of YAMLResume simple, and I am a bit hesitated to add multi languages support as we discussed here to YAMLResume core lib now, in my preference, YAMLResume should provide a solid, simple foundational design/lib, while multi languages should be lifted to upper, "application" level.

I will pin this issue for a while and see if there are more people voting here.

[tytyvillus]

Leaving the issue open to see what prople think sounds like a good idea.

Just a clarification — why do you say that locale.language would need to support arrays? In the way I imagined the solution, locale.language would only ever have one value, namely, the language into which to compile the document.

[xiaohanyu]

Just a clarification — why do you say that locale.language would need to support arrays? In the way I imagined the solution, locale.language would only ever have one value, namely, the language into which to compile the document.

YAMLResume by default support terms and idioms translations, for example, Bachelor in education section would be translated automatically to different terms based on locale.language, same translations happens to skill levels, language fluencies, country names, etc:

• https://yamlresume.dev/docs/locale/chinese#translations
• https://yamlresume.dev/docs/locale/french#translations

If support multilingual resumes in one YAML file, then yamlresum needs to know: "what is the target list of langauges in this YAML file to compile to when call yamlresume build?" and translate all terms accordingly based on the list of locale.language.

Hence we need to explicitly specify the target language as a list in locale.language.

[AleixMT]

Any way for me I still prefer to keep the the core lib of YAMLResume simple, and I am a bit hesitated to add multi languages support as we discussed here to YAMLResume core lib now, in my preference, YAMLResume should provide a solid, simple foundational design/lib, while multi languages should be lifted to upper, "application" level.

It is totally reasonable to keep it simple, but in my case, I am looking for a way to have everything in one place

[tytyvillus]

Just a clarification — why do you say that locale.language would need to support arrays? In the way I imagined the solution, locale.language would only ever have one value, namely, the language into which to compile the document.

YAMLResume by default support terms and idioms translations, for example, Bachelor in education section would be translated automatically to different terms based on locale.language, same translations happens to skill levels, language fluencies, country names, etc:

• https://yamlresume.dev/docs/locale/chinese#translations
• https://yamlresume.dev/docs/locale/french#translations

If support multilingual resumes in one YAML file, then yamlresum needs to know: "what is the target list of langauges in this YAML file to compile to when call yamlresume build?" and translate all terms accordingly based on the list of locale.language.

Hence we need to explicitly specify the target language as a list in locale.language.

Perhaps we are not talking about the same thing — in what I suggest, the compiled CV is never multilingual. There is only ever one output language at a time.

What is multilingual is the YAML file. As @AleixMT points out, this is just a way to keep user-written translations together.

[xiaohanyu]

Just a clarification — why do you say that locale.language would need to support arrays? In the way I imagined the solution, locale.language would only ever have one value, namely, the language into which to compile the document.

YAMLResume by default support terms and idioms translations, for example, Bachelor in education section would be translated automatically to different terms based on locale.language, same translations happens to skill levels, language fluencies, country names, etc:

• https://yamlresume.dev/docs/locale/chinese#translations
• https://yamlresume.dev/docs/locale/french#translations

If support multilingual resumes in one YAML file, then yamlresum needs to know: "what is the target list of langauges in this YAML file to compile to when call yamlresume build?" and translate all terms accordingly based on the list of locale.language.
Hence we need to explicitly specify the target language as a list in locale.language.

Perhaps we are not talking about the same thing — in what I suggest, the compiled CV is never multilingual. There is only ever one output language at a time.

What is multilingual is the YAML file. As @AleixMT points out, this is just a way to keep user-written translations together.

Hey, let us say that you have a resume as proposed like this:

content:
  basics:
    name: Andy Dufresne
    headline: 
      multi:
        en: Headed for the Pacific
        fr: En route vers le Pacifique
    phone: 
      multi:
        en: "(213) 555-9876"
        fr: "+1 213 555 98 76"
    email: hi@ppresume.com

locale:
  language: fr

If locale.language is only a string, when you build the resume, you will get a french version of resume, in either HTML/PDF/Markdown format right.

Then how would you get the English version of the resume? Manually modify locale.language to en?

What I suggest:

content:
  basics:
    name: Andy Dufresne
    headline: 
      multi:
        en: Headed for the Pacific
        fr: En route vers le Pacifique
    phone: 
      multi:
        en: "(213) 555-9876"
        fr: "+1 213 555 98 76"
    email: hi@ppresume.com

locale:
  language: 
    - en
    - fr

Here locale.language is a list of languages, and when yamlresume build my-resume.yml, it will generate the English and French version of resumes in one shot.

[tytyvillus]

I see your point, but I actually had in mind that the user would change locale.language and recompile. So let's say the original document is:

content:
  basics:
    name: Andy Dufresne
    headline: 
      en: Headed for the Pacific
      fr: En route vers le Pacifique
    phone: 
      en: "(213) 555-9876"
      fr: "+1 213 555 98 76"
    email: hi@ppresume.com

locale:
  language: fr

If the user compiles this, they get the French version. To get the English version, they change

locale:
  language: fr

to

locale:
  language: en

and rebuild. I feel like this generates less clutter than having the software generate multiple PDFs every time. It also means that if a user adds an fr: ... entry, say, and doesn't want to immediately add the corresponding en translation, the system won't complain about a missing translation.

Only if the user wants to actually generate the }en CV will they need to provide an English translation, which means that the translation can be provided on an only-once-needed basis.

[xiaohanyu]

If the user compiles this, they get the French version. To get the English version, they change

locale:
  language: fr

to

locale:
  language: en

and rebuild.

A tiny issue for this approach is, users need to rename the output in order to avoid conflict/override when switching languages.

For a resume my-resume.yml, by default yamlresume will generate pdf/html/md files in my-resume.pdf/my-resume.html/my-resume.md.

If you forget to rename the output filename, and when you switch the language, the generated output would be overriden.

That is another reason of why I propose to support a list of languages in locale.language, so yamlresume would generate my-resume.en.pdf, my-resume.fr.pdf, with language code as part of the filenames to avoid conflict and fully automate the process, if we would support multilingual yaml resumes.

[tytyvillus]

I think this is a matter of preference — after all, the output already gets overwritten very time you change the YAML file. Following the philosophy that the YAML source file is the actual CV from which you generate PDF/HTML/... representations, I suspect that users won't mind that the PDF file changes. (Even if you're using git, you're not tracking the PDF file as it's a binary file...)

Speaking for myself, my current set-up — which is a pandoc-based thing I cobbled together with a filter for the multilingual YAML file — overwrites the PDF file every time. Generating more files than the specific PDF file I need would just be clutter.

[xiaohanyu]

I think this is a matter of preference — after all, the output already gets overwritten very time you change the YAML file.〉

Yes yes, I understand your point. My point here is more about users' expectations and the semantics, i.e, if multilingual resume is supported, then generated multiple resumes in different languages in one shot should also be an expected behaviour in my opinion.

Anyway, let's see any others interested here.

[gulhe]

My personal preference would be to be able to write my resume in a single big file, with all the translations in the same place and locale as an array of preferred languages

content:
  basics:
    name:
      fr: André Vicomte du Fresne # let's say They are legally obligated to disclose their nobility since the french revolution
      en: Andy Dufresne # Internationnaly they prefer to keep it casual
    headline:
      fr: En route vers le Pacifique
      en: Headed for the Pacific
      es: Vamos a la playa
    phone: 
      en: "(213) 555-9876"
      fr: "+1 213 555 98 76"
    email: hi@ppresume.com
locale:
  language:
    - fr
    - en
    - es

Which, would generate 3 resume in one shot
The ruleset would be as follows :

• Any field with no translation is used as is
• Any field with the appropriate translation would use it
• Any field with a translation but missing the the one specific for the current local would use another (and raise a warning) using the locale.language[] order for preference order

You'd end up with files generated as if they'd have had resulted from the 3 following yaml :
🇫🇷

content:
  basics:
    name: André Vicomte du Fresne
    headline: En route vers le Pacifique
    phone: "+1 213 555 98 76"
    email: hi@ppresume.com
locale:
  language:
    - fr

🇬🇧

content:
  basics:
    name: Andy Dufresne
    headline: Headed for the Pacific
    phone: "(213) 555-9876"
    email: hi@ppresume.com
locale:
  language:
    - en

🇪🇸

Warning

Some fields are translated but the appropriate translation could not be found for current locale es, as per your locale.language[] setting other languages have been preferred fields and fallback language are :
content.basics.name: fr
content.basics.phone: fr

content:
  basics:
    name: André Vicomte du Fresne # We use nobility title since Spain's king agnatically descends from former french king Louis XIV ... (guillotine intensifies)
    headline: Vamos a la playa
    phone: "+1 213 555 98 76"
    email: hi@ppresume.com
locale:
  language:
    - es

This is what would work best for me.

(extra nice bonus would be if I could specify for which locale I want to generate files when sometimes I'd like to generate only a specific one withe something like yamlresume build --locale=es my-resume.yml)

[xiaohanyu]

hey @gulhe your proposal is a pretty nice design.

I may implement this after the first stable release of v1.0, but before v1.0, I would like to implement other high priority features like typst engine, gallery package, etc.

[gulhe]

Thanks for the compliment

I may implement this after the first stable release of v1.0, but before v1.0, I would like to implement other high priority features like typst engine, gallery package, etc.

Sure ! Those features seem awesome. Keep up the cool work and thank you very much for it !

I'm in no rush anyway I just wanted to contribute how this specific feature could make sense for my lazy brain 😉

[AleixMT]

I implemented this in #222 but I implemented other features and I need to split them in smaller PRs to merge them. If someone is really interested can take the work from this point. I will do it when I have time, but I am not sure when that will be.

[xiaohanyu]

OK I found that somebody use his own way to support multi-language translations:

https://github.com/brenopolanski/brenopolanski.com/blob/dev/resume/translations.pt-BR.yml

Interesting.

[tytyvillus]

OK I found that somebody use his own way to support multi-language translations:

https://github.com/brenopolanski/brenopolanski.com/blob/dev/resume/translations.pt-BR.yml

Interesting.

Huh. Interesting method, but it seems to me that changing the English-language string requires changing it in at least two places...

[xiaohanyu]

OK I found that somebody use his own way to support multi-language translations:
https://github.com/brenopolanski/brenopolanski.com/blob/dev/resume/translations.pt-BR.yml
Interesting.

Huh. Interesting method, but it seems to me that changing the English-language string requires changing it in at least two places...

yep that is right.

BTW, just got a new v0.16.0 release: https://github.com/yamlresume/yamlresume/releases/tag/v0.16.0, which started to provide an ai translate subcommand, which is relevant and may helpful for this issue.

[brenopolanski]

OK I found that somebody use his own way to support multi-language translations:

https://github.com/brenopolanski/brenopolanski.com/blob/dev/resume/translations.pt-BR.yml

Interesting.

Hey @xiaohanyu,

You are right that I solved multilingual support outside the core. I wanted to leave a few technical notes on why, and on gulh's proposal, which I think is the right long-term shape if this ever lands in the library.

What I built

resume.yml stays a valid, English-only YAMLResume document and the single source of truth for facts: dates, companies, URLs, metrics, skill lists, structure. I do not maintain a second hand-edited resume.

Wording lives in a separate translation memory:

resume.yml                  # canonical English content
translations.pt-BR.yml      # phrase map + locale / section aliases
        ↓
resume_pt.generated.yml     # valid YAMLResume file, overwritten every build
        ↓
yamlresume build            # once per language, unchanged

The memory is closer to gettext than to t('basics.headline'). Keys are the English strings themselves:

strings:
  'Software Engineer': 'Software Engineer'   # keep as-is
  'Systems Analyst': 'Analista de Sistemas'
  'Bronze Medal': 'Medalha de Bronze'

A small generator walks a known set of translatable fields (headline, summary bullets, position, area, award.title, award.awarder, skill category names), looks each string up, and writes a second YAMLResume file with locale.language: pt-br and localized section aliases. YAMLResume then does what it already does well: date formats, schema enums (degree, skill level), and PDF layout.

Two guards keep the languages from drifting:

1. A string in resume.yml with no memory entry fails the build. Identity mappings ('Software Engineer': 'Software Engineer') are explicit, so "leave this in English" is a decision, not a silent fallback.
2. A memory entry that no field uses is a warning. That caught a translation I wrote for awarder before the generator actually touched that field.

I deliberately do not translate company names, product names, technology tokens, or URLs. Those stay English in both PDFs.

Why this shape, and why not inline locales

@xiaohanyu's earlier comment in this thread is exactly why I stayed at the application layer:

• not every leaf is translatable, but which ones are is use-case specific
• string | Record<locale, string> blows up the JSON Schema and every consumer
• missing-locale / fallback rules are easy to get wrong for user-authored prose

Keeping resume.yml a plain string leaf meant I could keep using the published schema, yamlresume validate, and the existing compiler with zero core changes. The i18n file is the only extra surface.

The tradeoff @tytyvillus pointed out is real: if I rephrase an English bullet, I must also rename the key in translations.pt-BR.yml. The fail-on-missing guard makes that loud, but it is still two edits. For a resume that is edited often, that is the main weakness of a phrase-keyed memory.

t('work.dashfy.0') style keys would avoid that, but they are worse to read next to the English source, and they hide the source string. Phrase keys keep the translation file reviewable as a bilingual glossary, which mattered more to me for a 2-page resume than for a large app.

Why I like gulh's YAML

If this is going to live in YAMLResume itself, I would rather see gulh's model than either my glossary or t() placeholders.

content:
  basics:
    name:
      fr: André Vicomte du Fresne
      en: Andy Dufresne
    headline:
      fr: En route vers le Pacifique
      en: Headed for the Pacific
      es: Vamos a la playa
    phone:
      en: "(213) 555-9876"
      fr: "+1 213 555 98 76"
    email: hi@ppresume.com
locale:
  language:
    - fr
    - en
    - es

What I like, concretely:

1. Co-location. The French and English bullets sit on the same field. Updating a fact is one edit, not a hunt across files. That is the actual problem this issue is about, and it is the part my setup does not solve well.
2. Scalar = shared. email: hi@ppresume.com with no locale map is the right default. Most fields (URLs, company names, tech lists, often the person's name) should not be copied into every language.
3. Locale-specific scalars that are not "translations”. Phone formatting, a legal vs casual name, a localized /pt URL. My glossary cannot express those cleanly without pretending they are the same English string.
4. locale.language as an ordered list. One-shot yamlresume build → resume.fr.pdf, resume.en.pdf, resume.es.pdf matches how I already ship two PDFs. The order doubling as fallback preference is a good default. yamlresume build --locale=pt-br as an opt-in is the right escape hatch.
5. Fallback with a warning, not a silent English leak. For a resume, shipping a mixed-language bullet is worse than failing CI. I would treat fallback as a warning in local builds and a hard error under --strict / yamlresume validate.

A resolution rule I would add, from running this in production:

• plain string → use in every locale (identity)
• map containing the target locale → use it
• map missing the target locale → walk locale.language[], warn, and in CI fail
• do not invent translations for fields YAMLResume already localizes from the schema (Bachelor, skill levels, month names). Those should keep coming from locale.language, not from user maps.

That last point is why I never put degree or skill level in my memory file. Mixing "user prose” and "catalog terms” in the same mechanism will confuse both the schema and the fallback rules.

Schema, without bloating the public types

I agree the public JSON Schema should stay simple. A preprocess step is enough:

1. Walk the tree.
2. Resolve each leaf against the requested locale with the rules above.
3. Hand a normal string-leaf document to the existing validator and compiler.

Users who never use maps never see the feature. The published schema for the resolved document does not change. The multilingual file can be a thin "source schema” (string | record<locale, string> generated programmatically, as tytyvillus suggested) used only before resolution.

I would not require a multi: wrapper. It adds a level of nesting on every field and does not make the union any easier. A string vs a locale map is already explicit.

What I would not put in core

LLM sync between two YAML files, and t('basics.headline') + JSON catalogs, both work. I chose the catalog because I needed deterministic wording (ATS, first-person Portuguese verbs, Brazilian number format 1.000, job titles left in English for recruiter search). I would not want either of those as the only official path. They are application-layer, which is where my repo lives today.

If gulh's design lands after v1.0, I would migrate to it and delete the glossary. Until then, keeping the core a single-locale string tree and letting people preprocess is the right split.

Happy to answer anything about the generator or the pt-BR constraints if it helps the design.

[xiaohanyu]

@brenopolanski very very insightful response and solution.

Thank you! I feel that we almost aligned with @gulhe approach for multilingual YAMLResume.

I will implement this accordingly after v1.0.