Aller au contenu

Langues

Un calendrier affiche deux sortes de texte, qui ne viennent pas du même endroit. Les dates, les mois, les jours, les heures et les nombres sont écrits par l’Intl de la plateforme, dans toutes les langues, sans rien importer. Les mots du calendrier — « Aujourd’hui », « +3 autres », les menus, ce qu’on dit à un lecteur d’écran — sont ceux de DzCalendar, et viennent par lots, un par langue.

locale est une étiquette BCP 47. Elle décide de l’écriture des dates et des nombres, du lot de mots employé, du premier jour de la semaine (sauf si vous donnez firstDay) et du sens de lecture. L’anglais et le français sont intégrés. L’arabe, l’espagnol et l’allemand s’importent chacun à part, et ne pèsent que si on les importe :

import { createCalendar } from '@dzcalendar/dom';
import '@dzcalendar/dom/locales/es'; // aussi : …/locales/ar, …/locales/de
createCalendar(element, { timeZone: 'Europe/Madrid', locale: 'es-ES' });

L’étiquette est cherchée entière (es-MX), puis par sa langue (es), sinon les mots sont anglais. Une langue sans lot est tout de même écrite par la plateforme — locale: 'ja-JP' donne des dates et des nombres japonais — avec des boutons anglais : ajoutez ses mots comme on le voit plus bas. Sans locale, c’est la langue de la page (<html lang>), puis 'en'. Les extensions Unicode changent les nombres, pas les mots : ar-SA-u-nu-latn compte en chiffres latins.

messages ne prend que les mots qui changent ; les autres restent ceux de la langue. Les libellés du sélecteur de vue se fusionnent de la même façon, vue par vue :

import { createCalendar } from '@dzcalendar/dom';
const calendar = createCalendar(element, {
timeZone: 'Europe/Paris',
locale: 'fr-FR',
messages: { today: 'Ce jour', noEvents: 'Rien de prévu', views: { listWeek: 'Programme' } },
});
// Plus tard : un autre mot. Ce qu'un `messages` précédent donnait est remplacé.
calendar.update({ messages: { today: 'Maintenant' } });

Un mot que vous ne donnez pas reste celui de la langue : dans une langue sans lot, c’est donc l’anglais. Les mots qui portent un nombre ou un nom sont des fonctions (moreLink({ count }) pour « +3 autres ») ; un lot complet est décrit plus bas.

defineLocale(code, messages) enregistre les mots d’une langue, une fois, pour tous les calendriers de la page. DzMessages liste chaque mot et TypeScript signale celui qui manque ; partez d’un lot intégré et changez ce qui diffère. Une langue à vous définit aussi problem, la phrase d’un problème remis à onProblem (plus bas) :

import { EN, defineLocale } from '@dzcalendar/dom';
import { DE } from '@dzcalendar/dom/locales/de';
// Une langue : le portugais.
defineLocale('pt', {
...EN,
today: 'Hoje',
previous: 'Anterior',
next: 'Próximo',
allDay: 'Dia inteiro',
moreLink: ({ count }) => `+${count} mais`,
views: { ...EN.views, timeGridWeek: 'Semana', dayGridMonth: 'Mês' },
});
// Le vocabulaire d'une région : l'emporte sur `de` pour de-CH.
defineLocale('de-CH', { ...DE, today: 'Hüt' });

Le lot peut aussi être une fonction de l’étiquette entière, appelée une fois par étiquette de langue (pt-BR et pt-PT une fois chacune). C’est ainsi que l’arabe, l’espagnol et l’allemand intégrés suivent les nombres de l’étiquette ; les vôtres le peuvent aussi :

defineLocale('pt', (locale) => {
const n = new Intl.NumberFormat(locale);
return { ...EN, today: 'Hoje', moreLink: ({ count }) => `+${n.format(count)} mais` };
});

Les nombres et les pluriels passent par Intl.PluralRules et Intl.NumberFormat pour la langue — le lot arabe est l’exemple à lire pour les langues à plusieurs formes de pluriel. messagesForLocale(locale) renvoie les mots que le calendrier emploierait pour une étiquette.

Rien à activer. Le calendrier lit le sens d’écriture de locale — arabe, hébreu, persan, ourdou et les autres langues écrites de droite à gauche — et se met lui-même en dir="rtl". La grille est inversée : les jours vont de droite à gauche, les boutons précédent et suivant changent de côté, et les flèches gauche et droite du clavier suivent l’écran. Changer locale avec update() change le sens avec elle.

Les mots arabes sont un import (@dzcalendar/dom/locales/ar). La démonstration ci-dessous s’en passe : seulement la langue et quelques mots donnés par messages, le reste en anglais.

Laissée à la langue, la semaine commence le lundi dans la plus grande partie de l’Europe, le dimanche aux États-Unis et le samedi dans une bonne part du monde arabophone, et les semaines sont numérotées selon la règle des paramètres régionaux (semaines ISO en France, semaine contenant le 1er janvier aux États-Unis). firstDay impose le premier jour, en jour ISO (1 lundi … 7 dimanche) ; les numéros de weekNumbers le suivent alors, avec le nombre de jours minimal des paramètres régionaux. firstDay: null rend celui des paramètres régionaux.

import { createCalendar } from '@dzcalendar/dom';
// Mots et dates américains, semaines qui commencent le lundi.
const calendar = createCalendar(element, {
timeZone: 'America/Chicago',
locale: 'en-US',
initialView: 'dayGridMonth',
weekNumbers: true,
firstDay: 1,
});
// Plus tard : celui des paramètres régionaux.
calendar.update({ firstDay: null });

formats dit comment chaque endroit écrit ses dates et ses heures : le titre de l’en-tête, l’en-tête d’un jour, les heures de la marge, l’heure d’un événement, les jours de la liste, le numéro de semaine. Chaque endroit prend des options d’Intl.DateTimeFormat — écrites dans la langue du calendrier — ou une fonction qui renvoie le texte. titleFormat est le raccourci du titre, à la création.

import { createCalendar } from '@dzcalendar/dom';
const calendar = createCalendar(element, {
timeZone: 'Europe/Paris',
locale: 'fr-FR',
weekNumbers: true,
titleFormat: { month: 'long', year: 'numeric' },
formats: {
slotLabel: { hour: 'numeric' }, // « 09 h » au lieu de « 09:00 »
dayHeader: { weekday: 'short', day: 'numeric' }, // « lun. 19 »
weekNumber: ({ week }) => `Sem. ${week}`, // une fonction : la plateforme n'a pas de champ semaine
},
});
// Plus tard : des heures sur 24 h, avec les minutes.
calendar.update({ formats: { slotLabel: { hour: '2-digit', minute: '2-digit', hour12: false } } });

update({ formats }) remplace les formats donnés avant : redonnez-les tous. Une fonction qui lève une exception, ou des options que la plateforme refuse, est signalée une fois, et l’endroit revient à son écriture par défaut.

La grille et les données restent grégoriennes ; les dates peuvent s’écrire dans un autre calendrier. displayCalendar y écrit les titres et les numéros de jour ('islamic-umalqura', 'persian', 'hebrew', 'buddhist'…). secondaryCalendar garde le premier et ajoute une seconde date, en petit, à côté de chaque jour — pour les lecteurs qui comptent dans les deux. Un événement du 21 octobre reste au 21 octobre.

import { createCalendar } from '@dzcalendar/dom';
createCalendar(element, {
timeZone: 'Africa/Algiers',
locale: 'fr-DZ',
initialView: 'dayGridMonth',
secondaryCalendar: 'islamic-umalqura', // la date hégirienne sous chaque jour
});

locale, messages, formats et les calendriers sont tous modifiables à chaud : changez-les et le calendrier se redessine, son sens de lecture compris. Dans les frameworks ce sont des entrées, un état à vous suffit ; en JavaScript pur, appelez update(). Importez d’abord les lots dont vous pourriez avoir besoin.

import { createCalendar } from '@dzcalendar/dom';
import '@dzcalendar/dom/locales/es';
const calendar = createCalendar(element, { timeZone: 'Europe/Paris', locale: 'fr-FR' });
document.querySelector('#lang')!.addEventListener('change', (event) => {
calendar.update({ locale: (event.target as HTMLSelectElement).value });
});

Les mots que les gens lisent et entendent sont traduits : les boutons, les menus, les annonces du lecteur d’écran, un enregistrement refusé, une source qui n’a pas pu être chargée, une place refusée (saveFailed, loadFailed, violation…). Le detail d’un CalendarProblem remis à onProblem ou affiché dans la console l’est aussi : il est dans la langue du calendrier, par le message messages.problem(p), que définissent les lots anglais, français, arabe, allemand et espagnol, et que définit aussi une langue à vous. p est { code, … }, avec ce que porte chaque code : host-no-height { height }, zone-from-browser { zone }, too-many-occurrences { series, limit } et events-not-drawn { count, view, reason } (reason vaut 'all-day' ou 'hours'). Un programme doit toujours lire le code stable, non la phrase.

Ce qui reste en anglais, ce sont les problèmes de données que le noyau trouve dans les événements (calendar.kernel.getProblems() : invalid-start, offset-only…). Leur detail est une note de développeur ; si vous en montrez un à une personne, choisissez la phrase d’après le code, dans votre langue.