doc: translate the EdgeX's template in Korean :kr:

[flavono123]

Rules (found amending EdgeX template)

• notate the original word in the after bracket
  • pending, approved, amended and deprecated
  • since they are translated in phrase of Korean
  • and Korean users(developers, architect, ...) are familiar with them
• transcribe just as pronounciated(음차):
  • architecture -> 아키텍처
  • template -> 템플릿
  • pull request -> 풀 리퀘스트
  • issue -> 이슈
  • to distinct from 'problem' also translated in "문제"
• mis-translated
  • format -> 형식
• above rules would be applied to other templates after

[joelparkerhenderson]

Good. Try to do one tiny commit at a time, such as fixing just one concept, or one file, at a time.

It's fine to do many of these merge requests (a.k.a. pull requests).

One tiny commit is easier to merge than a work in progress branch.

[flavono123]

ok then, i will narrow down a scope of this PR to current 2 commits:

• rename directory names as English 6447541
• amend of edgex's template daaa59a (main of this PR) (and plus the minor one, 1f98b0f)

my plan, for now, is amending 1 template file for 1 commit(=1 PR), include fixes in previous ones if new rules come. i guess my first work is done with several PRs when amend around all template once for each.

and it would be helpful if there are the Korean reviewers. let me ask to my colleagues

[flavono123]

include fixes in previous ones if new rules come.

this could be in a separated and continued PR.

[joelparkerhenderson]

ok then, i will narrow down a scope of this PR to current 2 commits:

Aim to narrow even more. Good merge commits do one thing, and only one thing. This is because when other people pull your merged work, everyone is able to work faster if the change set is small and focused.

For this work you're doing, do the whitespace fix in one PR (which I'll merge immediately), and omit the Korean directory name change (because I need the directory names to match the language, and not be all English).

I can explain more if you want. Thanks!

[flavono123]

ok. that is for future people, anyway, i can agree with you. will split commits/PRs more:

• remove trailing white spaces
• change the link to correct (15b5f58)
• rename Korean directories to original English (6447541)
  • translate the edgex's template (b85f60f) - should be chained from above one

and omit the Korean directory name change (because I need the directory names to match the language, and not be all English).

you mean as from point of view split commits? or not changing for a while, to unify with other langs(fr, ...)

it would be good, btw, that describing your explanations in part of the contribution guide of this repo.

[joelparkerhenderson]

and omit the Korean directory name change (because I need the directory names to match the language, and not be all English).

you mean as from point of view split commits? or not changing for a while, to unify with other langs(fr, ...)

Sorry I was unclear. I mean that ideally one commit will have all Korean, meaning this...

1. the document uses Korean

2. the directory name uses Korean

3. the directory name is a Korean slug, meaning whatever Korean does for a typical web path slug, for example in English the slugs that I use are all lowercase alphanumeric and hyphen-minus without whitespace, symbols, uppercase, emoji, etc. I expect that Korean and other languages may have other kinds of slug processes, and I would like feedback about this formatting if you want.

For this specific pull request, if you can just delete the directory name change from Korean back to English (i.e. so the directory names end up as all Korean slugs), then I can merge this.

You're totally right that I should write this down. I'll aim for Monday morning. Thank you so much!

[joelparkerhenderson]

First draft of locales help: https://github.com/SixArm/locales-help

See what you think. I appreciate any feedback.

[flavono123]

• the reference link is not working. can you check? :)

For this specific pull request, if you can just delete the directory name change from Korean back to English (i.e. so the directory names end up as all Korean slugs), then I can merge this.

https://github.com/joelparkerhenderson/architecture-decision-record/issues/60#issuecomment-1783514830 as i said, i think the English directory names would be preferred

• but you are saying "no"
• (and maybe the link shows it)

debate on i18n directory names:

• again, my suggestion is all other langs except English, not even Korean, use same name with English's ones
  • pros:
  • as the index of this guide, the order for all locales will be same(if translated, orders are changed).
  • no/less issues for encoding/decoding on several envs(e.g. OS), you already concerned on French(https://github.com/joelparkerhenderson/architecture-decision-record/issues/60#issuecomment-1769590843)
  • cons:
    • need to translate? i think this is minor if the content is translated

[joelparkerhenderson]

Updates for you...

I added four little shell scripts that may help you; the scripts convert from markdown text to a headline slug, and also help find local peer id files: https://github.com/SixArm/locales-help

I added a documents directory and more content files.

For example this one is an introduction with content based on the top-level README:

• ./locales/en/documents/what-is-an-architecture-decision-record/index.md

In the documents directory, you can now see all these subdirectories, and each one contains the typical content file index.md, the symlink README.md for GitHub to work correctly, and the hidden file .locale-peer-id to help reference the corresponding directory in other locales:

• aws-adr-process
• decision-sustainability-criteria
• file-name-conventions-for-adrs
• guidelines-to-achieve-sustainable-decisions
• how-to-start-using-adrs
• how-to-start-using-adrs-with-git
• how-to-start-using-adrs-with-tools
• suggestions-for-writing-good-adrs
• teamwork-advice-for-adrs
• what-is-an-architecture-decision-record

I did a Google Translate of all the documents into all the existing locales, including Korean, which you can adjust as you wish whenever you're ready. Ideally one pull request per file (or per single concept change, such as correcting a word or phrase across all the files).

You asked about keeping the English directory names. Yes you're correct, I'm saying no to that, because that doesn't work well for the professional translators who are guiding me. I did a Google Translate of the Korean directory names, and you can adjust those as you wish in Korean, using whatever kind of slug-friendly format that you feel is best.

You're correct that there's a problem (or gap) when the directory names are translated and thus change their sort order. This is especially an issue for the top level file README.md which contains some sections that are lists of links, and some sections that are content text.

For my next step, I intend to try ways to improve that. So far I have not found an obvious way to handle this kind of work in any other project; if you discover one, I would be grateful to know.

I have added some small shell scripts that are helping me, and may help you, to this repo:

• https://github.com/SixArm/locales-help/

See the ./bin directory. The scripts help find directories with corresponding locale peer id files, and help convert from markdown text to a headline to a slug.

For your next step, can you remove the commit for the English directory names from this pull request? I believe that's all that's needed for us to do the merge for the content.

Thank you again for your help and your conversation here!

[flavono123]

unfortunately, i still cannot see the link of repo:

• https://github.com/SixArm/locales-help/

i guess maybe it is private?

ok. i agree some part and not. but it doesn't matter right now..

because that doesn't work well for the professional translators who are guiding me.

i think it sounds like you translate as your job somehow? interesting.

For your next step, can you remove the commit for the English directory names from this pull request? I believe that's all that's needed for us to do the merge for the content.

definitely. i think we can work for the "content" at least.

thank you for your kind explanation and hope to use your binary(shell scripts).

(or per single concept change, such as correcting a word or phrase across all the files).

totally agree with that and will do on next PRs. for lean works

[flavono123]

i did. the only commit here is for changing the content.

---

plus, i can do simple, a part of slugifying(Korean kebab-case), just replace spaces to dash(-)(some of them seems to be omitted).

feedback for above plz :)

[joelparkerhenderson]

Thank you.

For the help repo, does this link work for you now? https://github.com/SixArm/locale-help/

i think it sounds like you translate as your job somehow? interesting.

Yes you're on target. Several of my other projects involve translation, including professional translators, and translation government laws that require fully equal translations.

definitely. i think we can work for the "content" at least.

Great!

I'll merge your work so far now.

[flavono123]

no, the link for me:

[joelparkerhenderson]

I fixed the private -> public. Now does it work for you? https://github.com/SixArm/locale-help/settings