search

withastro / docs

Astro documentation
https://docs.astro.build/
MIT License
1.33k stars 1.48k forks source link

Glossaries for translation ? #474

Closed Chrissdroid closed 2 years ago

Chrissdroid commented 2 years ago

Each translation can be difficult and each language does not always have the same word for each concept used by astro

Glossary is like a white paper where translators refer to their approach in their language and ease the continuity between pages and sentence for a better understanding of the user

This issue is here to discuss how we can address this use case and make it available for each translation to have tools they need for the job

My first suggestion was to add a file named glossary.ts with defined terms and can be used for an auto-generated "glossary" page and components for defining abbreviations (with the <abbr> tag) and other words. But it can be tricky to do things the right way and contain issues with the approach.

The other idea was to create a simple glossary.md page but it can be tricky at a larger scale to maintain and keep track of.

Comment with your ideas if you think of another approach with this (like the use of GitHub's wiki, used for example by the french translation team from react docs)

delucis commented 2 years ago

Hi @Chrissdroid — great idea! Is this mainly intended as a glossary for translators to refer to or a public-facing glossary for Astro users?

Chrissdroid commented 2 years ago

I was thinking about translator-only at first, but it can technically be also useful for users if we include clear descriptions for each term

delucis commented 2 years ago

For translators I’d suggest adding a Markdown file in your language’s i18n folder, e.g. src/i18n/fr/glossary.md. A .ts file will likely be quite inflexible and we’d need the added wrangling of generating a page from it. With a Markdown file, each team can do what they want, add more or less and different kinds of comments.

Alternatively we could look at keeping this elsewhere so you can update and modify it more easily without needing to go through the PR process each time, but having it in the repo does help to keep things centralised.

Chrissdroid commented 2 years ago

But if the docs are well written, we dont technically need this for users

It's more like a chart for translators to refer to and know what words can translate to

Chrissdroid commented 2 years ago

Alternatively we could look at keeping this elsewhere so you can update and modify it more easily without needing to go through the PR process each time, but having it in the repo does help to keep things centralised.

I don't think making a PR when it changes is a problem in the long term, at the start, yes, because it needs to be adjusted first but then it won't normally change that much after that (except when a major release have a new concept to introduce)

sarah11918 commented 2 years ago

You might wish to START with a shared Google Doc (e.g.) to at least get quick, easy collaboration on an initial version.

I'm thinking of our poor PRs that only @delucis & I (mostly) will approve!

It's a lot of bureaucracy and "process" for that initial task!

Chrissdroid commented 2 years ago

@sarah11918 totally agree with that !

For the first iterations, this'll hopefully be done by each group on their side before coming with something (at least for the i18n-fr we'll discuss with everyone to agree on something that'll be good for everyone involved) and then PR'it when we're happy with the results