Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

FAQ updates from main repo #242

Merged
merged 36 commits into from
Jul 9, 2024
Merged

FAQ updates from main repo #242

merged 36 commits into from
Jul 9, 2024

Conversation

strump
Copy link
Sponsor Contributor

@strump strump commented Jun 12, 2024

Copied FAQ from https://github.com/organicmaps/organicmaps/blob/master/data/faq.html Nothing changed.

Added service page /faq/translation_status with all FAQ questions with translations as a table to track statuses.

FAQ categories need translations:

config.toml faq_section_app faq_section_bookmarks faq_section_editing faq_section_map faq_section_tts
EN App Bookmarks and tracks Map Editing Map Voice Directions
RU Общие Метки и Треки Редактирование Карта Голосовые подсказки
DE Anwendung Lesezeichen und Tracks Kartenbearbeitung Karte Sprachführung
ES Aplicación Marcadores y rutas Edición de mapas Mapa Instrucciones de voz
FR Application Signets et parcours Édition de la carte Carte Instructions vocales
IT Applicazione Luoghi preferiti e percorsi Modifica della mappa Mapa Istruzioni vocali
PL Aplikacja Zakładki i trasy Edycja mapy Mapa Komunikaty głosowe
PT Aplicativa Favoritos e trilhas Edição de mapas Mapa Instruções de voz
PT-BT Aplicativa Favoritos e trilhas Edição de mapas Mapa Orientação por voz
TR Başvuru Yer İmleri ve Kayıtlar Harita düzenleme Harita Sesli Yönlendirme
UK Загальні Мітки та Маршрути Редагування Мапа Голосові інструкції
ZH-Hans 应用 书签和轨迹 地图编辑 地图 语音指导

I think Roman's PR #115 could be closed.

Update 2022-06-17

Added "Edit on GitHub" link to every FAQ page.

Screenshot 2024-06-18 at 09 21 49

Should we translate link text?

Should we add the link to every page (now only FAQ pages have it)?

Should we move link to top? For example https://sphinx-rtd-theme.readthedocs.io/en/stable/ have github link on top.

Update 2022-06-18

Page /faq/translation_status now have coloring depending on last update date. Yellow cell color means that updated field is missing. Red cell means that translated page is older than English page.

Screenshot 2024-06-18 at 09 25 34

Coloring was implemented with Javascript 'cause Zola/Tera doesn't support strings or dates comparison. Only numbers could be compared with < operator 😕

Update 2022-06-21

FAQ sections are now translated in config.toml. So instead of faq: ["Map Editing"] we use faq: ["editing"] for all languages. And actual UI title is loaded from faq_section_editing string constant.

New translation constants:

  • faq_section_app = "App"
  • faq_section_bookmarks = "Bookmarks and Tracks"
  • faq_section_editing = "Map Editing"
  • faq_section_map = "Map"
  • faq_section_tts = "Voice Directions"

Update 2022-06-22

Updated README.md in FAQ section to reflect latest changes.

Update 2022-06-28

Updated /faq/translation_status page to work without JavaScript.


1. En Android, puede importar marcadores desde carpetas y aplicaciones (incluido Maps.Me). Presione un botón de estrella para abrir marcadores, presione "Importar marcadores" y seleccione la unidad o carpeta con archivos KML, KMZ, GPX.

2. Envía a ti mismo los archivos KML, KMZ, GPX por correo electrónico.* También puede usar mensajería instantánea o almacenamiento en la nube, como iCloud o Google Drive.
Copy link
Sponsor Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's that asterisk * symbol?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's a typo, it should be removed.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@strump ^^^

@strump
Copy link
Sponsor Contributor Author

strump commented Jun 12, 2024

Should we synchronize organicmaps/data/faq.html file with this repo? Some Python script to copy text from MD to HTML?

Copy link

cloudflare-workers-and-pages bot commented Jun 12, 2024

Deploying organicmaps with  Cloudflare Pages  Cloudflare Pages

Latest commit: 9f182c0
Status: ✅  Deploy successful!
Preview URL: https://ba39b946.organicmaps.pages.dev
Branch Preview URL: https://faq-updates-from-main-repo.organicmaps.pages.dev

View logs

@biodranik
Copy link
Member

Thanks a lot for your work! I love the translation status page! Is it possible in addition to compare FAQ article dates, and mark translations as outdated if they were not changed after the English md file was edited?

Left some comments, it would be great to also sync ru, uk and other languages.

@@ -0,0 +1,10 @@
---
title: Frequently Asked Questions {translate me}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. Can this string's translation be taken from the main app?
  2. Will the site build/work if we add all _index.lang.md stubs in /faq/ without adding translations?

Copy link
Sponsor Contributor Author

@strump strump Jun 17, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. I tried to use translations from config.toml writing:
title: "{{ trans(key='faq-menu-title', lang='pl') }}"

But it didn't work. Looks like we can use trans() code only in Markdown body.

Screenshot 2024-06-17 at 22 29 46
  1. We can generate content/faq/_index.##.md files for all languages. But if there are no taxonomies then Zola doesn't generate /##/faq/ page and user will see error page:
You're seeing this page because we couldn't find a template to render.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. No, I meant to insert translations from strings.txt below into each .md file directly.
  2. If the main site is built ok, without any references to missing pages, then it's acceptable. Otherwise, let's translate only necessary langs for now and add other translations later.
  [faq]
    comment = Button in the main Help dialog
    tags = android,ios
    en = Frequently Asked Questions
    af = Gereelde vrae
    ar = اسئلة مكررة
    az = Tez-tez soruşulan suallar
    be = Пытанні і адказы
    bg = Въпроси и отговори
    ca = Preguntes més freqüents
    cs = Otázky a odpovědi
    da = Spørgsmål og svar
    de = Häufige Fragen und Antworten
    el = Συχνές ερωτήσεις
    es = Preguntas frecuentes
    et = Korduma kippuvad küsimused
    eu = Ohiko galderak
    fa = پرسش‌های زیاد پرسیده شده
    fi = Usein kysytyt kysymykset
    fr = Foire aux questions
    he = שאלות ותשובות
    hi = अक्सर पूछे जाने वाले प्रश्नों
    hu = Gyakran Ismételt Kérdések
    id = Pertanyaan dan jawaban
    it = Domande frequenti
    ja = よくある質問
    ko = 질문과 답변
    lt = Dažniausiai užduodami klausimai
    mr = वारंवार विचारलेले प्रश्न
    nb = Spørsmål og svar
    nl = Vragen en antwoorden
    pl = Pytania i odpowiedzi
    pt = Perguntas frequentes
    ro = Întrebări frecvente
    ru = Вопросы и ответы
    sk = Otázky a odpovede
    sv = Frågor och svar
    sw = Maswali na majibu
    th = คำถามและคำตอบ
    tr = Sıkça Sorulan Sorular
    uk = Питання та відповіді
    vi = Câu hỏi và trả lời
    zh-Hans = 问题和解答
    zh-Hant = 問題和解答

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@strump you can use DeepL as the initial version. And then tag our translate groups on Github (for selected languages only) to review automated translations.

Copy link
Sponsor Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated FAQ description in content/faq/_index.##.md files using DeepL.

But I don't know how to translage 'F.A.Q.' menu item into German. Please review

content/faq/app/crash/index.md Outdated Show resolved Hide resolved
order: 10
---

Choose a bookmark on the map, tap it and then tap “Share” button in the place page. To share all bookmarks in a list at once, tap the double star symbol on the main screen, tap the icon with three dots in front of name of the list with bookmarks and tap Export file in the pop-up window.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Choose a bookmark on the map, tap it and then tap “Share” button in the place page. To share all bookmarks in a list at once, tap the double star symbol on the main screen, tap the icon with three dots in front of name of the list with bookmarks and tap Export file in the pop-up window.
Tap a bookmark on the map or in the list, and then tap the "Share" button on the place page.
To share all bookmarks and tracks in a list from the Bookmarks and Tracks dialog, tap the icon with three dots in front of the name of the list with bookmarks and tap the Export KML/KMZ or Export GPX in the pop-up window.

@strump please confirm that for iOS and Android three dots are present.

Copy link
Sponsor Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirming: three dots are present on Android and iOS (iPadOS).

content/faq/bookmarks/how-to-export/index.md Outdated Show resolved Hide resolved
content/faq/bookmarks/how-to-import/index.md Outdated Show resolved Hide resolved
content/faq/map/cant-download-maps/index.md Outdated Show resolved Hide resolved
content/faq/map/cant-download-maps/index.md Outdated Show resolved Hide resolved
content/faq/map/search-cannot-find-a-place/index.md Outdated Show resolved Hide resolved
content/faq/map/search-cannot-find-a-place/index.md Outdated Show resolved Hide resolved
content/faq/bookmarks/how-to-export/index.md Outdated Show resolved Hide resolved
@rtsisyk
Copy link
Member

rtsisyk commented Jun 18, 2024

Is there any preview page on Cloudflare? I can't find a link.

@strump
Copy link
Sponsor Contributor Author

strump commented Jun 18, 2024

@rtsisyk try https://faq-updates-from-main-repo.organicmaps.pages.dev

Did you see this block?

Screenshot 2024-06-18 at 12 42 56

@rtsisyk
Copy link
Member

rtsisyk commented Jun 21, 2024

https://faq-updates-from-main-repo.organicmaps.pages.dev

It was hidden. Thanks!!!

Copy link
Member

@rtsisyk rtsisyk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Thanks for finally getting FAQ in the right place.

Copy link
Member

@biodranik biodranik left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great, thanks! A few comments.

@organicmaps/translations can you please review translations in your language, and suggest full translations if your language is missing?

config.toml Outdated Show resolved Hide resolved
config.toml Outdated Show resolved Hide resolved
config.toml Outdated Show resolved Hide resolved
config.toml Outdated Show resolved Hide resolved
@@ -4,7 +4,7 @@ description: ""
updated: "2024-06-12"

taxonomies:
faq: ["Загальні"]
faq: ["app"]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the benefit of using English taxonomy everywhere instead of localized one? Isn't a localized one (present in the URL) improving the SEO by catching relevant search requests?

A translator can add a translation here, just in one place, without referencing something in the config. Isn't it simpler?

Copy link
Sponsor Contributor Author

@strump strump Jun 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that all FAQ translations should be in a single file for simplicity. If we decide to rename "Map Editing" to "Map Changes" this could be done in a config without touching MD files. Also typos could lead to extra sections. If user writes "Bookmarks and Tracks" and "Bookmark and track" those would be treated as two different taxonomies.

Disadvantage of such approach: we need to translate all strings even if there is no FAQ pages. For example there is no TTS FAQ page in German but I had to add faq_section_tts translation to German language.

And if we add new section such as "ios" it should be translated to all FAQ languages or we'll get Zola errors.

Copy link
Member

@biodranik biodranik Jun 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The comparison of two approaches:

  1. FAQ section/taxonomy translations are stored in config.toml
    Pros:
  • When translations should be changed, only a single file is edited

Cons:

  • URLs do not have translated keywords, they always have English translation key, that is not good for SEO
  • When adding a single new FAQ page, all taxonomies in config.toml should be translated if the language is missing, even if these categories are not used/added yet.
  1. FAQ section translations are embedded in each FAQ article's taxonomy

Pros:

  • Better SEO as the URLs are translated and contain important keywords
  • Easier to add new languages/FAQ articles in a new language (no need to translate all FAQ sections, only the currently added one needs translation)
  • Simpler to translators and reviewers, they type the translated taxonomy directly into an article, in one file, instead of guessing which translation key from a config should be used (another article in the same section can be copy-pasted and edited)

Cons:

  • If a FAQ taxonomy/section should be renamed, all contained pages should be edited (renaming is bad for SEO, not sure that there's an alias support here, we may need to add manual aliases in this case)
  • Typos in every single file may lead to extra sections (can it be avoided by adding a validator script btw?)

@strump did I miss something? So far the benefits from the second approach look worth it, no?

config.toml Outdated Show resolved Hide resolved
config.toml Outdated Show resolved Hide resolved
@@ -4,7 +4,7 @@ description: ""
updated: "2024-06-12"

taxonomies:
faq: ["Bookmarks"]
faq: ["bookmarks"]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: Can the key contain spaces? "bookmarks and tracks"? Or dashes? Then it would be easier to translate properly (and a better SEO).

Copy link
Sponsor Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Currently I use simple concatenation "faq_section_" + taxonome_term to get translation constant faq_section_tts. We can allow spaces and hyphens using Zola built-in regex-replace function.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So this key should also match the directory name where pages are located, right?


1. En Android, puede importar marcadores desde carpetas y aplicaciones (incluido Maps.Me). Presione un botón de estrella para abrir marcadores, presione "Importar marcadores" y seleccione la unidad o carpeta con archivos KML, KMZ, GPX.

2. Envía a ti mismo los archivos KML, KMZ, GPX por correo electrónico.* También puede usar mensajería instantánea o almacenamiento en la nube, como iCloud o Google Drive.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's a typo, it should be removed.

content/faq/bookmarks/how-to-import/index.md Outdated Show resolved Hide resolved
Added Ukrainian FAQ index.
Fixed missing FAQ translation errors.

Signed-off-by: S. Kozyr <[email protected]>
…e an error. Added translation placeholders `{translate me}`

Signed-off-by: S. Kozyr <[email protected]>
Copy link
Member

@biodranik biodranik left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @strump ! A few comments.

README.md Outdated
@@ -91,13 +90,16 @@ taxonomies = [
]
[languages.XX.translations]
faq-menu-title = "{Translation of 'F.A.Q.' to a new language}"
faq_section_app = "App"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it still needed?

Copy link
Sponsor Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed.

README.md Outdated
| ... | ... | ... |
| File | Taxonomy key | Taxonomy value |
|-----------------------------------------| ------------ |----------------|
| map/can-find-position/index.md | `faq` | `map` |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| map/can-find-position/index.md | `faq` | `map` |
| map/can-not-find-position/index.md | `faq` | `map` |

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should it be capitalized? e.g. Map, App?

Copy link
Sponsor Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renamed faq/map/can-find-position to faq/map/can-not-find-position
Updated "Taxonomy value" column

README.md Outdated Show resolved Hide resolved
README.md Outdated

- For key `/faq/` with the list of values (see `templates/faq/list.html`)
- For each value `/faq/general`, `/faq/android`, etc. with the list of questions (see `templates/faq/single.html`)
- For each value `/faq/app`, `/faq/map`, etc. with the list of questions (see `templates/faq/single.html`)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does it make sense to mention that for other languages taxonomies should be translated for better SEO?

Copy link
Sponsor Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added translated taxonomies samples: /es/faq/aplicacion/ and /de/faq/karte/


1. En Android, puede importar marcadores desde carpetas y aplicaciones (incluido Maps.Me). Presione un botón de estrella para abrir marcadores, presione "Importar marcadores" y seleccione la unidad o carpeta con archivos KML, KMZ, GPX.

2. Envía a ti mismo los archivos KML, KMZ, GPX por correo electrónico.* También puede usar mensajería instantánea o almacenamiento en la nube, como iCloud o Google Drive.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@strump ^^^

content/faq/bookmarks/how-to-import/index.ru.md Outdated Show resolved Hide resolved
content/faq/bookmarks/how-to-import/index.ru.md Outdated Show resolved Hide resolved
content/faq/bookmarks/how-to-import/index.ru.md Outdated Show resolved Hide resolved
templates/faq/translation_status.html Show resolved Hide resolved
Renamed `faq/map/can-find-position` to `faq/map/can-not-find-position`.
Added `KMB` to the list of supported formats.
Updated button title 'Import Bookmarks and Tracks' according to strings.txt from main repo.
Updated README.md

Signed-off-by: S. Kozyr <[email protected]>
Signed-off-by: Alexander Borsuk <[email protected]>
Copy link
Member

@biodranik biodranik left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@strump thank you for your titanic work! The next step is to add necessary translations to existing articles, and add new FAQ articles.

@biodranik biodranik merged commit bb813de into master Jul 9, 2024
3 checks passed
@biodranik biodranik deleted the faq-updates-from-main-repo branch July 9, 2024 12:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants