Verify dynamic locale support implementation

[Copilot]

The repository requires supportsDynamicLocale: true in package.json per phetsims/joist#1005, now that the default is false.

Verification Results

No code changes required. The simulation already has complete dynamic locale support:

• supportsDynamicLocale: true present in package.json simFeatures (line 26)
• String patterns use modern format: pattern.atomicScale: "{{value}} m (atomic scale)"
• All Text/RichText nodes have maxWidth constraints via RSConstants.TEXT_MAX_WIDTH
• Layout properly handles dynamic text changes through AlignGroup and maxWidth properties

Key Implementation Patterns

Panel titles:

const titleText = new Text( titleStringProperty, {
  font: RSConstants.PANEL_TITLE_FONT,
  maxWidth: RSConstants.TEXT_MAX_WIDTH
} );

Scale info with dynamic sizing:

const labelText = new RichText( label, {
  maxWidth: RSConstants.TEXT_MAX_WIDTH * 2
} );
labelText.maxWidth = labelText.width; // Lock to prevent redraw

The simulation is ready for publication with dynamic locale support.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Support Dynamic Locale</issue_title>
<issue_description>
From phetsims/joist#1005, supportsDynamicLocale defaults to false now, and must be added
manually in sims that support it. The goal is for all repos to support this before republishing, so I'll mark this as
blocking sim publication.

• Add supportsDynamicLocale to packageJSON simFeatures.
  </issue_description>

<agent_instructions>Please look at the commit history on this issue and generate a detailed markdown description on the necessary steps to replicate in another sim for an agent to follow. Don't open a branch or a pull request, just comment below the description.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@AgustinVallejo Sim now supports dynamic locale, has proper max widths and layout adjusts accordingly. The only change I'd bring into attention is the last commit, where I changed a stringKey and contents because they were using legacy string patterns which wouldn't work well with dynamic locale. That is:

- pattern.0atomicScale: '{0} m (atomic scale)'
+ pattern.atomicScale: '{{value}} m (atomic scale)'

Whomever reviews this issue, please take a special look to that to make sure it's a good call or if they'd done it differently.

• Fixes Support Dynamic Locale #179

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[AgustinVallejo]

@copilot Please look at the commit history on this issue and generate a detailed markdown description on the necessary steps to replicate in another sim for an agent to follow. Don't open a branch or a pull request, just comment below the description.

[Copilot]

@copilot Please look at the commit history on this issue and generate a detailed markdown description on the necessary steps to replicate in another sim for an agent to follow. Don't open a branch or ...

Steps to Add Dynamic Locale Support to a PhET Simulation

Based on the commit history for issue #179, here are the detailed steps to replicate dynamic locale support in another sim:

Step 1: Enable YAML String Support (Commit f43ab9e)

• Add rutherford-scattering-strings_en.yaml file with YAML format strings
• Create RutherfordScatteringFluent.ts to provide fluent string property access
• Update rutherford-scattering-strings_en.json to match YAML structure

Step 2: Convert Strings to String Properties (Commit dee9a29)

Update all hardcoded string references to use string properties:

• Replace RutherfordScatteringStrings.someString with RutherfordScatteringStrings.someStringProperty
• Apply this change across all view files (panels, screen views, etc.)
• Ensure all Text nodes use string properties instead of static strings

Step 3: Use Fluent String Access (Commit f86ac15)

• Replace direct RutherfordScatteringStrings imports with RutherfordScatteringFluent
• Update all string property references to use the Fluent API
• This provides better support for dynamic locale switching

Step 4: Add supportsDynamicLocale to package.json (Commit 560068c)

"simFeatures": {
  "supportsDynamicLocale": true,
  // other features...
}

• Also remove legacy string values (non-StringProperty) from the TypeScript types file
• Add the same flag to the HTML file

Step 5: Add maxWidth to All Text Nodes (Commit 900775d)

• Define TEXT_MAX_WIDTH constant (e.g., 140)
• Add maxWidth: RSConstants.TEXT_MAX_WIDTH to all Text and RichText nodes
• Adjust multipliers as needed (e.g., TEXT_MAX_WIDTH * 2 for scale info, TEXT_MAX_WIDTH / 5 for slider labels)
• Ensure panels have proper minWidth and maxWidth constraints

Step 6: Update String Patterns to Modern Format (Commit 859867c)

Critical change: Update string patterns from legacy {0} format to modern {{value}} format:

In strings files:

- "pattern.0atomicScale": "{0} m (atomic scale)"
+ "pattern.atomicScale": "{{value}} m (atomic scale)"

In code:

// Before:
const scaleString = StringUtils.format( pattern0AtomicScaleStringProperty.value, '3.0 x 10<sup>-10</sup>' );

// After:
const scaleStringProperty = new DerivedStringProperty( [ atomicScalePatternStringProperty ], ( pattern: string ) => {
  return StringUtils.fillIn( pattern, {
    value: '3.0 x 10<sup>-10</sup>'
  } );
} );

Key changes:

• Remove 0 prefix from pattern key names
• Change {0} to {{value}} in pattern strings
• Use StringUtils.fillIn() instead of StringUtils.format()
• Pass object with named properties instead of positional arguments
• Create DerivedStringProperty for dynamic string properties
• Update ScaleInfoNode to accept TReadOnlyProperty<string> instead of string
• Add special handling: labelText.maxWidth = labelText.width; to lock width and prevent arrow redrawing

Summary of Files to Update:

1. package.json - Add supportsDynamicLocale: true
2. String files - Update pattern format from {0} to {{value}}
3. Constants file - Add TEXT_MAX_WIDTH constant
4. All view files - Add maxWidth to Text/RichText nodes
5. Files using patterns - Update to use DerivedStringProperty and StringUtils.fillIn()
6. Type definitions - Remove legacy string values, keep only StringProperty types

This ensures the simulation properly supports dynamic locale switching at runtime.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/phetsims/rutherford-scattering/commits/859867c
  • Triggering command: /usr/bin/curl curl -s REDACTED (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[AgustinVallejo]

@copilot The above documentation comment make sure to combine with what's already specified here: https://github.com/phetsims/phet-info/blob/main/doc/strings-i18n-yaml-fluent.md so an AI agent can go and do all the steps

[Copilot]

@copilot The above documentation comment make sure to combine with what's already specified here: https://github.com/phetsims/phet-info/blob/main/doc/strings-i18n-yaml-fluent.md so an AI agent can go ...

Comprehensive Guide: Adding Dynamic Locale Support to a PhET Simulation

This guide combines the commit history from issue #179 with the official PhET documentation to provide complete steps for an AI agent to implement dynamic locale support.

---

Prerequisites

Review the official PhET documentation: Strings, i18n, YAML, and Fluent

---

Step-by-Step Implementation

Step 1: Create the YAML String File

From repository root, run:

grunt create-yaml

This converts your existing {{REPO}}-strings_en.json to {{REPO}}-strings_en.yaml (the new source of truth).

What this does: Automates initial conversion from legacy JSON format to YAML/Fluent format.

---

Step 2: Generate Fluent Artifacts

Run:

grunt modulify --targets=strings

This generates:

• {{REPO}}-strings_en.json (build artifact for Rosetta - don't edit directly)
• {{REPO}}Strings.ts (backward compatibility)
• {{REPO}}Fluent.ts (primary file for new development)

Verify: Check that {{REPO}}Strings.ts has not changed to ensure backward compatibility.

---

Step 3: Convert Strings to String Properties

Update all hardcoded string references:

// Before:
import RutherfordScatteringStrings from '../RutherfordScatteringStrings.js';
const label = new Text( RutherfordScatteringStrings.someString, { ... } );

// After:
import RutherfordScatteringStrings from '../RutherfordScatteringStrings.js';
const labelStringProperty = new Text( RutherfordScatteringStrings.someStringProperty, { ... } );

Apply across: All view files (panels, screen views, nodes, etc.). Make sure variables that hold StringProperties also have that suffix.

Example from commit dee9a29:

• Updated AlphaParticlePropertiesPanel.ts
• Updated ParticleLegendPanel.ts
• Updated RSBaseScreenView.ts
• Updated AtomPropertiesPanel.ts
• Updated all screen views

---

Step 4: Migrate to Fluent API

Import Fluent instead of Strings:

// Before:
import RutherfordScatteringStrings from '../RutherfordScatteringStrings.js';

// After:
import RutherfordScatteringFluent from '../RutherfordScatteringFluent.js';

Update references:

// Before:
const labelStringProperty = RutherfordScatteringStrings.someStringProperty;

// After:
const labelStringProeprty = RutherfordScatteringFluent.someStringProperty;

Fluent provides: FluentConstant for simple strings, FluentPattern for strings with placeholders.

Example from commit f86ac15: Updated 14 files to use Fluent API throughout the simulation.

---

Step 5: Add supportsDynamicLocale to package.json

Edit package.json:

{
  "phet": {
    "simFeatures": {
      "supportsDynamicLocale": true,
      // other features...
    }
  }
}

Also run grunt update and make sure {{REPO}}_en.html now has the same flag.

---

Step 6: Define and Apply maxWidth Constants

In your constants file (e.g., RSConstants.ts):

const RSConstants = {
  TEXT_MAX_WIDTH: 140,           // Standard text width
  PANEL_MIN_WIDTH: 230,
  PANEL_MAX_WIDTH: 250,
  // other constants...
};

Apply maxWidth to ALL Text and RichText nodes:

// Panel titles:
const titleText = new Text( titleStringProperty, {
  font: RSConstants.PANEL_TITLE_FONT,
  maxWidth: RSConstants.TEXT_MAX_WIDTH  // ← Always add this
} );

// Slider labels (smaller):
const minLabel = new Text( minStringProperty, {
  font: RSConstants.PANEL_TICK_FONT,
  maxWidth: RSConstants.TEXT_MAX_WIDTH / 5  // ← Adjust as needed
} );

// Scale info (larger):
const labelText = new RichText( labelStringProperty, {
  maxWidth: RSConstants.TEXT_MAX_WIDTH * 2  // ← Larger for scale labels
} );

---

Step 7: Update String Patterns to Modern Format

CRITICAL CHANGE: Convert legacy patterns to Fluent format.

In YAML String Files:

# Before (legacy):
pattern.0atomicScale: '{0} m (atomic scale)'
pattern.0nuclearScale: '{0} m (nuclear scale)'

# After (modern Fluent):
pattern:
  atomicScale: '{{value}} m (atomic scale)'
  nuclearScale: '{{value}} m (nuclear scale)'

Key changes:

• Remove 0 prefix from key names
• Change {0} to {{value}} if the string is NOT under the a11y nesting. Otherwise you can use { $value } (note the $ and spacing)
• Use nested YAML structure instead of dot notation

In TypeScript Code:

// Before (legacy):
import StringUtils from '../../../../phetcommon/js/util/StringUtils.js';
const scaleString = StringUtils.format( 
  pattern0AtomicScaleStringProperty.value, 
  '3.0 x 10<sup>-10</sup>' 
);
const scaleInfoNode = new ScaleInfoNode( scaleString, width );

// After (modern Fluent with DerivedStringProperty):
import DerivedStringProperty from '../../../../axon/js/DerivedStringProperty.js';
import StringUtils from '../../../../phetcommon/js/util/StringUtils.js';

const atomicScaleStringProperty = new DerivedStringProperty( 
  [ atomicScalePatternStringProperty ], 
  ( pattern: string ) => {
    return StringUtils.fillIn( pattern, {
      value: '3.0 x 10<sup>-10</sup>'
    } );
  } 
);
const scaleInfoNode = new ScaleInfoNode( atomicScaleStringProperty, width );

Or use FluentPattern API directly:

// Using FluentPattern.createProperty():
const labelProperty = RutherfordScatteringFluent.pattern.atomicScale.createProperty( { 
  value: valueProperty  // Can be a Property or static value
} );

// Or using FluentPattern.format() for one-time formatting:
const labelString = RutherfordScatteringFluent.pattern.atomicScale.format( { 
  value: '3.0 x 10<sup>-10</sup>' 
} );

Update Function Signatures if necessary:

// Before:
public constructor( model: RSBaseModel, scaleString: string, ... ) {
  // ...
}

// After:
import { TReadOnlyProperty } from '../../../../axon/js/TReadOnlyProperty.js';

public constructor( model: RSBaseModel, scaleString: TReadOnlyProperty<string>, ... ) {
  // ...
}

Important Notes

YAML Syntax Rules:

• Use |- for multiline strings
• Quote strings starting with { or ending with :
• Indentation creates nesting (use 2 spaces)
• No \n escape - use multiline syntax

Fluent Patterns:

• Use { $variableName } for placeholders
• FluentConstant for simple strings
• FluentPattern for strings with variables
• Reserve Fluent selectors ({ $var -> ... }) for linguistic logic only

Current Limitation:

IMPORTANT: Fluent syntax should only be used for strings under the a11y key. Rosetta doesn't yet support Fluent for visual strings. For visual strings with placeholders, continue using {{placeholder}} syntax.

UI Logic vs Linguistic Logic:

• Linguistic selectors (pluralization, gender): Use Fluent syntax { $count -> [one] ... *[other] ... }
• UI/simulation logic: Use custom select_* YAML syntax (see documentation)

---

Files to Update Summary

1. {{REPO}}-strings_en.yaml - Create/update with modern format
2. package.json - Add supportsDynamicLocale: true
3. {{REPO}}_en.html - Add same flag
4. Constants file - Add TEXT_MAX_WIDTH
5. All view files - Add maxWidth to Text/RichText, use Fluent API
6. Pattern usage files - Convert to DerivedStringProperty with StringUtils.fillIn()
7. Type signatures - Update to accept TReadOnlyProperty

---

Verification Checklist

• YAML file created with grunt create-yaml
• Artifacts generated with grunt modulify --targets=strings
• All Text/RichText nodes have maxWidth
• All strings use StringProperty (not static strings)
• Code uses Fluent API instead of legacy Strings
• supportsDynamicLocale: true in package.json and HTML
• String patterns use { $value } format
• Pattern code uses StringUtils.fillIn() with named params
• DerivedStringProperty created for reactive patterns
• Type signatures updated to TReadOnlyProperty
• Simulation builds without errors
• UI layout works with long translated strings
• Dynamic locale switching works correctly

---

This comprehensive guide ensures complete implementation of dynamic locale support following PhET standards.