From 770e0a67e667545513640fa0599be8a4e528d9f6 Mon Sep 17 00:00:00 2001 From: Jesse Date: Wed, 5 Feb 2025 11:31:00 -0500 Subject: [PATCH] improve documentation for https://github.com/phetsims/joist/issues/994 --- js/browser-and-node/FluentLibrary.ts | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/js/browser-and-node/FluentLibrary.ts b/js/browser-and-node/FluentLibrary.ts index f4c6f820..3d0dd4de 100644 --- a/js/browser-and-node/FluentLibrary.ts +++ b/js/browser-and-node/FluentLibrary.ts @@ -110,15 +110,14 @@ class FluentLibrary { throw new Error( `These terms are not defined: [ ${undefinedTermsFormatted} ]` ); } - // Terms are not allowed to use placeables because terms used in placeables cannot take forwarded variables. - // This is a PhET specific catch. Fluent allows translators to use terms with placeables and specify cases - // in the translation, see https://projectfluent.org/fluent/guide/terms.html. But it is an easy programming - // mistake to assume that terms with placeables can be used like messages so we catch it loudly here. + // In the PhET project, terms with placeables are prohibited since they can't accept forwarded variables. + // Fluent allows this for translation flexibility (see: https://projectfluent.org/fluent/guide/terms.html), + // but it can be misleading, causing developers to treat terms like messages. We enforce this check to prevent errors. Array.from( collector.declaredTerms ).forEach( ( term: IntentionalAny ) => { if ( term && term.value && term.value.elements && term.value.elements.some( ( element: IntentionalAny ) => element.type === 'Placeable' ) ) { - throw new Error( `Terms with placeables are not allowed: -${term.id.name} ` ); + throw new Error( `Terms with placeables are not allowed: -${term.id.name}. Use a Message instead.` ); } } );