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

feat: add admonition type title translations #7556

Merged
merged 6 commits into from Jun 3, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
79 changes: 62 additions & 17 deletions packages/docusaurus-theme-classic/src/theme/Admonition/index.tsx
Expand Up @@ -7,6 +7,8 @@

import React, {type ReactNode} from 'react';
import clsx from 'clsx';
import {ThemeClassNames} from '@docusaurus/theme-common';
import Translate from '@docusaurus/Translate';
import type {Props} from '@theme/Admonition';

import styles from './styles.module.css';
Expand Down Expand Up @@ -69,41 +71,82 @@ function CautionIcon() {
type AdmonitionConfig = {
iconComponent: React.ComponentType;
infimaClassName: string;
label: ReactNode;
};

const AdmonitionConfigs: {[key: string]: AdmonitionConfig | string} = {
// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
const AdmonitionConfigs: Record<Props['type'], AdmonitionConfig> = {
note: {
infimaClassName: 'secondary',
iconComponent: NoteIcon,
label: (
<Translate
id="theme.admonition.note"
description="The default label used for the Note admonition (:::note)">
note
</Translate>
),
},
tip: {
infimaClassName: 'success',
iconComponent: TipIcon,
label: (
<Translate
id="theme.admonition.tip"
description="The default label used for the Tip admonition (:::tip)">
tip
</Translate>
),
},
danger: {
infimaClassName: 'danger',
iconComponent: DangerIcon,
label: (
<Translate
id="theme.admonition.danger"
description="The default label used for the Danger admonition (:::danger)">
danger
</Translate>
),
},
info: {
infimaClassName: 'info',
iconComponent: InfoIcon,
label: (
<Translate
id="theme.admonition.info"
description="The default label used for the Info admonition (:::info)">
info
</Translate>
),
},
caution: {
infimaClassName: 'warning',
iconComponent: CautionIcon,
label: (
<Translate
id="theme.admonition.caution"
description="The default label used for the Caution admonition (:::caution)">
caution
</Translate>
),
},
};

// Legacy aliases, undocumented but kept for retro-compatibility
const aliases = {
secondary: 'note',
important: 'info',
success: 'tip',
warning: 'danger',
Copy link
Collaborator

Choose a reason for hiding this comment

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

"Warning" is used more often than "danger", at least for our docs. Do we really want to not translate it?

Copy link
Collaborator Author

@slorber slorber Jun 3, 2022

Choose a reason for hiding this comment

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

good point, this is a bit annoying to have these aliases and would require duplicating some translation duplication

btw I'm not fan at all of "caution". "warning" is more natural to me.

Do we really need different default labels for both cases?

Is there a good reason to use both on our own website, or is it just historically the case?

Copy link
Collaborator

Choose a reason for hiding this comment

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

I agree that "warning" = "danger" and "caution" being another thing is not at all obvious😅 I can't even think of two distinct words for "warning" and "caution" in Chinese. Maybe we can keep it like this, since it... should be better than what we had?

TBH, on Crowdin, I never translate the admonition titles, because using "tip"/"info" is actually more natural than using any Chinese characters in the title. Maybe that's just me.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

@forresst do you find it useful to have 2 orange admonitions for warning/caution ?

They are currently translated in French as "avertissement" / "attention", but to me we could as well use "attention" for both and it would remain a good translation

Copy link
Contributor

Choose a reason for hiding this comment

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

@slorber You are right. I agree with you. One is enough. "attention" is perfect

Copy link
Collaborator

@Josh-Cena Josh-Cena Jun 3, 2022

Choose a reason for hiding this comment

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

I'm not good at French at all, but I struggle to capture the nuance between "warning" and "caution" in my Chinese translations. "Caution" does sound less severe than "warning". I think "avertissement" is more severe than "attention" (forgive my ignorance if that's not true)?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

@forresst personally I find "Attention" more usual in French and would use it in both cases

I guess all this is quite subjective 🤪 hopefully it is now customizable

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

oh yes, I'm misunderstanding things now.

Our alias "warning" -> "danger" feels really wrong to me. To me a warning should be yellow/orange.

BTW it looks like I'm not alone to think so

https://v1.vuepress.vuejs.org/guide/markdown.html#custom-containers

https://nextra.vercel.app/themes/docs/callout

https://vitepress.vuejs.org/guide/markdown.html#custom-containers

https://docs.gitbook.com/editing-content/rich-content/with-command-palette#hints-and-callouts

I'll open a dedicated issue, we should probably do like all others, but we need a way to migrate this gracefully or this will be annoying for our users

Copy link
Collaborator

Choose a reason for hiding this comment

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

That's very right. It has always been tricky for me as well. A breaking change is probably worth it, considering :::warning wasn't documented anyway...

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

};
} as const;

function getAdmonitionConfig(type: string): AdmonitionConfig {
function getAdmonitionConfig(
unsafeType: Props['type'] | keyof typeof aliases,
): AdmonitionConfig {
const type = aliases[unsafeType as keyof typeof aliases] ?? unsafeType;
const config = AdmonitionConfigs[type];
if (config) {
if (typeof config === 'string') {
return AdmonitionConfigs[config] as AdmonitionConfig;
}
return config;
}
console.warn(
Expand Down Expand Up @@ -136,28 +179,30 @@ function processAdmonitionProps(props: Props): Props {
const {mdxAdmonitionTitle, rest} = extractMDXAdmonitionTitle(props.children);
return {
...props,
title: props.title ?? mdxAdmonitionTitle ?? props.type,
title: props.title ?? mdxAdmonitionTitle,
children: rest,
};
}

export default function Admonition(props: Props): JSX.Element {
const {
children,
type,
title = type,
icon: iconProp,
} = processAdmonitionProps(props);
const {children, type, title, icon: iconProp} = processAdmonitionProps(props);

const config = getAdmonitionConfig(type);
const {infimaClassName, iconComponent: IconComponent} = config;
const typeConfig = getAdmonitionConfig(type);
const titleLabel = title ?? typeConfig.label;
const {iconComponent: IconComponent} = typeConfig;
const icon = iconProp ?? <IconComponent />;
return (
<div
className={clsx('alert', `alert--${infimaClassName}`, styles.admonition)}>
className={clsx(
ThemeClassNames.common.admonition,
ThemeClassNames.common.admonitionType(props.type),
'alert',
`alert--${typeConfig.infimaClassName}`,
styles.admonition,
)}>
<div className={styles.admonitionHeading}>
<span className={styles.admonitionIcon}>{icon}</span>
{title}
{titleLabel}
</div>
<div className={styles.admonitionContent}>{children}</div>
</div>
Expand Down
11 changes: 7 additions & 4 deletions packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts
Expand Up @@ -31,19 +31,22 @@ export const ThemeClassNames = {
docsPages: 'docs-wrapper',
mdxPages: 'mdx-wrapper',
},

/**
* Follows the naming convention "theme-{blog,doc,version,page}?-<suffix>"
*/
common: {
editThisPage: 'theme-edit-this-page',
lastUpdated: 'theme-last-updated',
backToTopButton: 'theme-back-to-top-button',
codeBlock: 'theme-code-block',
admonition: 'theme-admonition',
admonitionType: (type: 'note' | 'tip' | 'danger' | 'info' | 'caution') =>
`theme-admonition-${type}`,
},
layout: {
// TODO add other stable classNames here
},

/**
* Follows the naming convention "theme-{blog,doc,version,page}?-<suffix>"
*/
docs: {
docVersionBanner: 'theme-doc-version-banner',
docVersionBadge: 'theme-doc-version-badge',
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "يرجى الاتصال بمالك الموقع الذي ربطك بعنوان URL الأصلي وإخباره بأن الارتباط الخاص به معطل.",
"theme.NotFound.title": "الصفحة غير موجودة",
"theme.TOCCollapsible.toggleButtonLabel": "محتويات هذه الصفحة",
"theme.admonition.caution": "caution",
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
"theme.blog.archive.description": "Archive",
"theme.blog.archive.title": "Archive",
"theme.blog.paginator.navAriaLabel": "التنقل في صفحة قائمة المدونة",
Expand Down
Expand Up @@ -25,6 +25,16 @@
"theme.NotFound.title___DESCRIPTION": "The title of the 404 page",
"theme.TOCCollapsible.toggleButtonLabel": "On this page",
"theme.TOCCollapsible.toggleButtonLabel___DESCRIPTION": "The label used by the button on the collapsible TOC component",
"theme.admonition.caution": "caution",
"theme.admonition.caution___DESCRIPTION": "The default label used for the Caution admonition (:::caution)",
"theme.admonition.danger": "danger",
"theme.admonition.danger___DESCRIPTION": "The default label used for the Danger admonition (:::danger)",
"theme.admonition.info": "info",
"theme.admonition.info___DESCRIPTION": "The default label used for the Info admonition (:::info)",
"theme.admonition.note": "note",
"theme.admonition.note___DESCRIPTION": "The default label used for the Note admonition (:::note)",
"theme.admonition.tip": "tip",
"theme.admonition.tip___DESCRIPTION": "The default label used for the Tip admonition (:::tip)",
"theme.blog.archive.description": "Archive",
"theme.blog.archive.description___DESCRIPTION": "The page & hero description of the blog archive page",
"theme.blog.archive.title": "Archive",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "দয়া করে সাইটের মালিকের সাথে যোগাযোগ করুন যা আপনাকে মূল URL এর সাথে যুক্ত করেছে এবং তাদের লিঙ্কটি ভাঙ্গা রয়েছে তা তাদের জানান।",
"theme.NotFound.title": "পেজটি খুঁজে পাওয়া যায়নি",
"theme.TOCCollapsible.toggleButtonLabel": "এই পেজ এ রয়েছে",
"theme.admonition.caution": "caution",
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
"theme.blog.archive.description": "Archive",
"theme.blog.archive.title": "Archive",
"theme.blog.paginator.navAriaLabel": "ব্লগ তালিকা পেজ নেভিগেশন",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "Kontaktujte prosím vlastníka webu, který vás odkázal na původní URL a upozorněte ho, že jejich odkaz nefunguje.",
"theme.NotFound.title": "Stránka nenalezena",
"theme.TOCCollapsible.toggleButtonLabel": "Na této stránce",
"theme.admonition.caution": "caution",
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
"theme.blog.archive.description": "Archive",
"theme.blog.archive.title": "Archive",
"theme.blog.paginator.navAriaLabel": "Stránkování článků na blogu",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "Venligst kontakt ejeren til webstedet, som førte dig frem denne URL, og informer dem om at linket ikke virker.",
"theme.NotFound.title": "Siden blev ikke fundet",
"theme.TOCCollapsible.toggleButtonLabel": "On this page",
"theme.admonition.caution": "caution",
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
"theme.blog.archive.description": "Archive",
"theme.blog.archive.title": "Archive",
"theme.blog.paginator.navAriaLabel": "Blogoversigt navigation",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "Bitte kontaktieren Sie den Besitzer der Seite, die Sie mit der ursprünglichen URL verlinkt hat, und teilen Sie ihm mit, dass der Link nicht mehr funktioniert.",
"theme.NotFound.title": "Seite nicht gefunden",
"theme.TOCCollapsible.toggleButtonLabel": "Auf dieser Seite",
"theme.admonition.caution": "caution",
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
"theme.blog.archive.description": "Archiv",
"theme.blog.archive.title": "Archiv",
"theme.blog.paginator.navAriaLabel": "Navigation der Blog-Listenseite",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "Comuníquese con el dueño del sitio que lo vinculó a la URL original y hágale saber que su vínculo está roto.",
"theme.NotFound.title": "Página No Encontrada",
"theme.TOCCollapsible.toggleButtonLabel": "En esta página",
"theme.admonition.caution": "caution",
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
"theme.blog.archive.description": "Archivo",
"theme.blog.archive.title": "Archivo",
"theme.blog.paginator.navAriaLabel": "Navegación por la página de la lista de blogs ",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "لطفا با صاحب وبسایت تماس بگیرید و ایشان را از مشکل پیش آمده مطلع کنید.",
"theme.NotFound.title": "صفحه ای که دنبال آن بودید پیدا نشد.",
"theme.TOCCollapsible.toggleButtonLabel": "مطالب این صفحه",
"theme.admonition.caution": "caution",
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

cc @massoudmaboudi translations to suggest?

"theme.blog.archive.description": "آرشیو",
"theme.blog.archive.title": "آرشیو",
"theme.blog.paginator.navAriaLabel": "کنترل لیست مطالب وبلاگ",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "Mangyaring makipag-ugnayan sa may-ari ng site na nag-link sa iyo sa orihinal na URL at sabihin sa kanila na ang kanilang link ay putol.",
"theme.NotFound.title": "Hindi Nahanap ang Pahina",
"theme.TOCCollapsible.toggleButtonLabel": "On this page",
"theme.admonition.caution": "caution",
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
"theme.blog.archive.description": "Archive",
"theme.blog.archive.title": "Archive",
"theme.blog.paginator.navAriaLabel": "Nabegasyón para sa pahina na listahan ng blog",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "Veuillez contacter le propriétaire du site qui vous a lié à l'URL d'origine et leur faire savoir que leur lien est cassé.",
"theme.NotFound.title": "Page introuvable",
"theme.TOCCollapsible.toggleButtonLabel": "Sur cette page",
"theme.admonition.caution": "attention",
slorber marked this conversation as resolved.
Show resolved Hide resolved
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "remarque",
"theme.admonition.tip": "astuce",
"theme.blog.archive.description": "Archive",
"theme.blog.archive.title": "Archive",
"theme.blog.paginator.navAriaLabel": "Pagination de la liste des articles du blog",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "הקישור אינו תקין, אנא פנה למנהל האתר ממנו קיבלת קישור זה.",
"theme.NotFound.title": "דף לא נמצא",
"theme.TOCCollapsible.toggleButtonLabel": "בעמוד זה",
"theme.admonition.caution": "caution",
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
"theme.blog.archive.description": "Archive",
"theme.blog.archive.title": "Archive",
"theme.blog.paginator.navAriaLabel": "רשימת דפי הבלוג",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "कृपया उस साइट के मालिक से संपर्क करें जिसने आपको मूल URL से जोड़ा है और उन्हें बताएं कि उनका लिंक टूट गया है।",
"theme.NotFound.title": "पेज नहीं मिला",
"theme.TOCCollapsible.toggleButtonLabel": "इस पेज पर",
"theme.admonition.caution": "caution",
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
"theme.blog.archive.description": "Archive",
"theme.blog.archive.title": "Archive",
"theme.blog.paginator.navAriaLabel": "ब्लॉग सूची पेज नेविगेशन",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "Contatta il proprietario del sito che ti ha collegato all'URL originale e fagli sapere che il loro collegamento è interrotto.",
"theme.NotFound.title": "Pagina non trovata",
"theme.TOCCollapsible.toggleButtonLabel": "Su questa pagina",
"theme.admonition.caution": "caution",
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
"theme.blog.archive.description": "Archivio",
"theme.blog.archive.title": "Archivio",
"theme.blog.paginator.navAriaLabel": "Navigazione nella pagina dei post del blog ",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "このページにリンクしているサイトの所有者に連絡をしてリンクが壊れていることを伝えてください。",
"theme.NotFound.title": "ページが見つかりません",
"theme.TOCCollapsible.toggleButtonLabel": "On this page",
"theme.admonition.caution": "caution",
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
"theme.blog.archive.description": "Archive",
"theme.blog.archive.title": "Archive",
"theme.blog.paginator.navAriaLabel": "ブログ記事一覧のナビゲーション",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "사이트 관리자에게 링크가 깨진 것을 알려주세요.",
"theme.NotFound.title": "페이지를 찾을 수 없습니다.",
"theme.TOCCollapsible.toggleButtonLabel": "이 페이지에서",
"theme.admonition.caution": "caution",
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

cc @koko8829 @leeyspaul , translations to suggest?

"theme.blog.archive.description": "게시물 목록",
"theme.blog.archive.title": "게시물 목록",
"theme.blog.paginator.navAriaLabel": "블로그 게시물 목록 탐색",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "Proszę skontaktuj się z właścielem strony, z której link doprowadził Cię tutaj i poinformuj go, że link jest nieprawidłowy.",
"theme.NotFound.title": "Strona nie została znaleziona",
"theme.TOCCollapsible.toggleButtonLabel": "Na tej stronie",
"theme.admonition.caution": "caution",
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
"theme.blog.archive.description": "Archiwum",
"theme.blog.archive.title": "Archiwum",
"theme.blog.paginator.navAriaLabel": "Nawigacja na stronie listy wpisów na blogu",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "Entre em contato com o proprietário do site que lhe trouxe para cá e lhe informe que o link está quebrado.",
"theme.NotFound.title": "Página não encontrada",
"theme.TOCCollapsible.toggleButtonLabel": "Nessa página",
"theme.admonition.caution": "caution",
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

cc @sseraphini , translations to suggest? 😄

"theme.blog.archive.description": "Arquivo",
"theme.blog.archive.title": "Arquivo",
"theme.blog.paginator.navAriaLabel": "Navegação da página de listagem do blog",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "Por favor, contacte o proprietário do site que o trouxe aqui e informe-lhe que o link está partido.",
"theme.NotFound.title": "Página não encontrada",
"theme.TOCCollapsible.toggleButtonLabel": "On this page",
"theme.admonition.caution": "caution",
"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
"theme.blog.archive.description": "Archive",
"theme.blog.archive.title": "Archive",
"theme.blog.paginator.navAriaLabel": "Navegação da página de listagem do blog",
Expand Down
Expand Up @@ -12,6 +12,11 @@
"theme.NotFound.p2": "Пожалуйста, обратитесь к владельцу сайта, с которого вы перешли на эту ссылку, чтобы сообщить ему, что ссылка не работает.",
"theme.NotFound.title": "Страница не найдена",
"theme.TOCCollapsible.toggleButtonLabel": "Содержание этой страницы",
"theme.admonition.caution": "caution",
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

cc @lex111 , want to provide translations?

"theme.admonition.danger": "danger",
"theme.admonition.info": "info",
"theme.admonition.note": "note",
"theme.admonition.tip": "tip",
"theme.blog.archive.description": "Архив",
"theme.blog.archive.title": "Архив",
"theme.blog.paginator.navAriaLabel": "Навигация по странице списка блогов",
Expand Down