@tldraw/editor 5.5.4 → 5.6.0-canary.0091c91994d6

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tldraw/editor",
   "description": "tldraw infinite canvas SDK (editor).",
-  "version": "5.5.4",
+  "version": "5.6.0-canary.0091c91994d6",
   "author": {
     "name": "tldraw Inc.",
     "email": "hello@tldraw.com"
@@ -39,27 +39,16 @@
     "dist-cjs",
     "src"
   ],
-  "scripts": {
-    "test-ci": "yarn run -T vitest run --passWithNoTests",
-    "test": "yarn run -T vitest --passWithNoTests",
-    "test-coverage": "yarn run -T vitest run --coverage --passWithNoTests",
-    "build": "yarn run -T tsx ../../internal/scripts/build-package.ts",
-    "build-api": "yarn run -T tsx ../../internal/scripts/build-api.ts",
-    "prepack": "yarn run -T tsx ../../internal/scripts/prepack.ts",
-    "postpack": "../../internal/scripts/postpack.sh",
-    "pack-tarball": "yarn pack",
-    "lint": "yarn run -T tsx ../../internal/scripts/lint.ts"
-  },
   "dependencies": {
     "@tiptap/core": "^3.12.1",
     "@tiptap/pm": "^3.12.1",
     "@tiptap/react": "^3.12.1",
-    "@tldraw/state": "5.5.4",
-    "@tldraw/state-react": "5.5.4",
-    "@tldraw/store": "5.5.4",
-    "@tldraw/tlschema": "5.5.4",
-    "@tldraw/utils": "5.5.4",
-    "@tldraw/validate": "5.5.4",
+    "@tldraw/state": "5.6.0-canary.0091c91994d6",
+    "@tldraw/state-react": "5.6.0-canary.0091c91994d6",
+    "@tldraw/store": "5.6.0-canary.0091c91994d6",
+    "@tldraw/tlschema": "5.6.0-canary.0091c91994d6",
+    "@tldraw/utils": "5.6.0-canary.0091c91994d6",
+    "@tldraw/validate": "5.6.0-canary.0091c91994d6",
     "classnames": "^2.5.1",
     "eventemitter3": "^4.0.7",
     "idb": "^7.1.1",
@@ -79,7 +68,6 @@
     "@types/react-dom": "^19.2.3",
     "@types/wicg-file-system-access": "^2020.9.8",
     "fake-indexeddb": "^4.0.2",
-    "lazyrepo": "0.0.0-alpha.27",
     "react": "^19.2.1",
     "react-dom": "^19.2.1",
     "resize-observer-polyfill": "^1.5.1",
@@ -96,5 +84,15 @@
       "require": "./dist-cjs/index.js"
     },
     "./editor.css": "./editor.css"
+  },
+  "scripts": {
+    "test-ci": "pnpm exec vitest run --passWithNoTests",
+    "test": "pnpm exec vitest --passWithNoTests",
+    "test-coverage": "pnpm exec vitest run --coverage --passWithNoTests",
+    "build": "pnpm exec tsx ../../internal/scripts/build-package.ts",
+    "build-api": "pnpm exec tsx ../../internal/scripts/build-api.ts",
+    "pack-tarball": "pnpm pack",
+    "lint": "pnpm exec tsx ../../internal/scripts/lint.ts",
+    "build-types": "tsc --build"
   }
 }

package/src/index.ts

@@ -75,6 +75,17 @@ export {
 	type TLEditorSnapshot,
 	type TLLoadSnapshotOptions,
 } from './lib/config/TLEditorSnapshot'
+export {
+	defaultI18n,
+	defineMessages,
+	getDeclaredMessages,
+	translateMessage,
+	type TLI18n,
+	type TLI18nAdapter,
+	type TLI18nMessage,
+	type TLI18nMessageInput,
+	type TLI18nValues,
+} from './lib/config/TLI18n'
 export {
 	createSessionStateSnapshotSignal,
 	extractSessionStateFromLegacySnapshot,
@@ -439,17 +450,18 @@ export {
 } from './lib/primitives/utils'
 export { Vec, type VecLike } from './lib/primitives/Vec'
 export {
+	EditorI18nFallbackContext,
 	ErrorScreen,
 	LoadingScreen,
-	TldrawEditor,
-	useOnMount,
 	type LoadingScreenProps,
+	TldrawEditor,
 	type TldrawEditorBaseProps,
 	type TldrawEditorProps,
 	type TldrawEditorStoreProps,
 	type TldrawEditorWithoutStoreProps,
 	type TldrawEditorWithStoreProps,
 	type TLOnMountHandler,
+	useOnMount,
 } from './lib/TldrawEditor'
 export { dataUrlToFile, getDefaultCdnBaseUrl } from './lib/utils/assets'
 export { clampToBrowserMaxCanvasSize, type CanvasMaxSize } from './lib/utils/browserCanvasMaxSize'

package/src/lib/TldrawEditor.tsx

@@ -32,6 +32,7 @@ import { TLAnyAssetUtilConstructor } from './config/defaultAssets'
 import { TLAnyBindingUtilConstructor } from './config/defaultBindings'
 import { TLAnyShapeUtilConstructor } from './config/defaultShapes'
 import { TLEditorSnapshot } from './config/TLEditorSnapshot'
+import { defaultI18n, TLI18nAdapter } from './config/TLI18n'
 import { Editor } from './editor/Editor'
 import { resolveThemes } from './editor/managers/ThemeManager/ThemeManager'
 import { TLAnyOverlayUtilConstructor } from './editor/overlays/OverlayUtil'
@@ -253,6 +254,11 @@ export interface TldrawEditorBaseProps {
 	 * The URLs for the fonts to use in the editor.
 	 */
 	assetUrls?: { fonts?: { [key: string]: string | undefined } }
+
+	/**
+	 * An i18n adapter for translating strings.
+	 */
+	i18n?: TLI18nAdapter
 }
 
 /**
@@ -484,6 +490,23 @@ const TldrawEditorWithLoadingStore = memo(function TldrawEditorBeforeLoading({
 
 const noAutoFocus = () => getGlobalDocument().location.search.includes('tldraw_preserve_focus')
 
+/**
+ * A slot the UI fills with its own i18n, for an editor whose host passed none. Every app that
+ * composes `<TldrawEditor>` and `<TldrawUi>` by hand rather than rendering `<Tldraw>` is one: the
+ * `i18n` prop is new, so none of them pass it, and their shape names — which shapes now resolve
+ * through the editor's i18n — would have been announced in English. The UI renders inside the
+ * editor in every composition, so it can hand its translations up. An `i18n` prop still wins.
+ *
+ * `<Tldraw>` relies on this too, rather than passing a prop: the translation provider it renders
+ * above the editor has its locale fixed at mount, so an adapter read from there kept announcing
+ * shapes in the first language after the user switched.
+ *
+ * @internal
+ */
+export const EditorI18nFallbackContext = React.createContext<{
+	current: TLI18nAdapter | null
+} | null>(null)
+
 function TldrawEditorWithReadyStore({
 	onMount,
 	children,
@@ -505,6 +528,7 @@ function TldrawEditorWithReadyStore({
 	assetUrls,
 	themes,
 	initialTheme,
+	i18n,
 }: Required<
 	TldrawEditorProps & {
 		store: TLStore
@@ -549,6 +573,18 @@ function TldrawEditorWithReadyStore({
 		}
 	}, [autoFocus, initialState, colorScheme, cameraOptions, deepLinks, themes, initialTheme])
 
+	// The adapter is called on each use rather than held as a value, so the editor can keep one
+	// stable function that reads whichever adapter is current. Listing `i18n` among the deps that
+	// recreate the editor instead tore it down — camera, selection, undo history — whenever the
+	// adapter's identity changed, which is every render for one written inline.
+	const i18nRef = useRef(i18n)
+	i18nRef.current = i18n
+	const fallbackI18nRef = useRef<TLI18nAdapter | null>(null)
+	const stableI18n = useCallback<TLI18nAdapter>(
+		() => (i18nRef.current ?? fallbackI18nRef.current ?? defaultI18n)(),
+		[]
+	)
+
 	useLayoutEffect(
 		() => {
 			const {
@@ -580,6 +616,7 @@ function TldrawEditorWithReadyStore({
 				fontAssetUrls: assetUrls?.fonts,
 				themes: themes,
 				initialTheme: initialTheme,
+				i18n: stableI18n,
 			})
 			editor.licenseManager = licenseManager
 
@@ -620,6 +657,7 @@ function TldrawEditorWithReadyStore({
 			licenseManager,
 			getShapeVisibility,
 			assetUrls,
+			stableI18n,
 		]
 	)
 
@@ -767,10 +805,12 @@ function TldrawEditorWithReadyStore({
 				<Crash crashingError={crashingError} />
 			) : (
 				<EditorProvider editor={editor}>
-					<Layout onMount={onMount}>
-						{children ?? (Canvas ? <Canvas key={editor.contextId} /> : null)}
-						<Watermark />
-					</Layout>
+					<EditorI18nFallbackContext.Provider value={fallbackI18nRef}>
+						<Layout onMount={onMount}>
+							{children ?? (Canvas ? <Canvas key={editor.contextId} /> : null)}
+							<Watermark />
+						</Layout>
+					</EditorI18nFallbackContext.Provider>
 				</EditorProvider>
 			)}
 		</OptionalErrorBoundary>

package/src/lib/components/default-components/DefaultErrorFallback.tsx

@@ -1,7 +1,13 @@
 import { useValue } from '@tldraw/state-react'
 import { noop } from '@tldraw/utils'
 import classNames from 'classnames'
-import { ComponentType, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { ComponentType, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import {
+	defineMessages,
+	translateMessage,
+	type TLI18nMessage,
+	type TLI18nValues,
+} from '../../config/TLI18n'
 import { Editor } from '../../editor/Editor'
 import { getOwnerDocument } from '../../exports/domUtils'
 import { useEditorComponents } from '../../hooks/EditorComponentsContext'
@@ -12,6 +18,50 @@ import { ErrorBoundary } from '../ErrorBoundary'
 
 const BASE_ERROR_URL = 'https://github.com/tldraw/tldraw/issues/new'
 
+const messages = defineMessages({
+	confirmResetTitle: { id: 'error.confirm-reset.title', defaultMessage: 'Are you sure?' },
+	confirmResetDescription: {
+		id: 'error.confirm-reset.description',
+		defaultMessage: 'Resetting your data will delete your drawing and cannot be undone.',
+	},
+	cancel: { id: 'error.cancel', defaultMessage: 'Cancel' },
+	resetData: { id: 'error.reset-data', defaultMessage: 'Reset data' },
+	title: { id: 'error.title', defaultMessage: 'Something went wrong' },
+	refreshHint: { id: 'error.refresh-hint', defaultMessage: 'Please refresh your browser.' },
+	resetHint: {
+		id: 'error.reset-hint',
+		defaultMessage:
+			'If the issue continues after refreshing, you may need to reset the tldraw data stored on your device.',
+	},
+	noteLabel: { id: 'error.note-label', defaultMessage: 'Note:' },
+	resetNote: {
+		id: 'error.reset-note',
+		defaultMessage: 'Resetting will erase your current project and any unsaved work.',
+	},
+	messageLabel: { id: 'error.message-label', defaultMessage: 'Message:' },
+	stackTraceLabel: { id: 'error.stack-trace-label', defaultMessage: 'Stack trace:' },
+	copy: { id: 'error.copy', defaultMessage: 'Copy' },
+	copied: { id: 'error.copied', defaultMessage: 'Copied!' },
+	showDetails: { id: 'error.show-details', defaultMessage: 'Show details' },
+	hideDetails: { id: 'error.hide-details', defaultMessage: 'Hide details' },
+	refreshPage: { id: 'error.refresh-page', defaultMessage: 'Refresh page' },
+})
+
+// This renders because something already threw, so reading the editor is done defensively the way
+// the rest of this component reads it: English beats a second crash on the error screen.
+function useErrorMsg(editor: Editor | undefined) {
+	return useCallback(
+		(message: TLI18nMessage, values?: TLI18nValues) => {
+			try {
+				return translateMessage(editor?.i18n(), message, values)
+			} catch {
+				return message.defaultMessage
+			}
+		},
+		[editor]
+	)
+}
+
 /** @public */
 export interface TLErrorFallbackProps {
 	/** The error that was caught. */
@@ -28,6 +78,7 @@ export type TLErrorFallbackComponent = ComponentType<TLErrorFallbackProps>
 
 /** @public @react */
 export function DefaultErrorFallback({ error, editor }: TLErrorFallbackProps) {
+	const msg = useErrorMsg(editor)
 	const containerRef = useRef<HTMLDivElement>(null)
 	const [shouldShowError, setShouldShowError] = useState(process.env.NODE_ENV === 'development')
 	const [didCopy, setDidCopy] = useState(false)
@@ -168,27 +219,24 @@ My browser: ${navigator.userAgent}`
 			>
 				{shouldShowResetConfirmation ? (
 					<>
-						<h2>Are you sure?</h2>
-						<p>Resetting your data will delete your drawing and cannot be undone.</p>
+						<h2>{msg(messages.confirmResetTitle)}</h2>
+						<p>{msg(messages.confirmResetDescription)}</p>
 						<div className="tl-error-boundary__content__actions">
 							<button className="tlui-button" onClick={() => setShouldShowResetConfirmation(false)}>
-								Cancel
+								{msg(messages.cancel)}
 							</button>
 							<button className="tlui-button tl-error-boundary__reset" onClick={resetLocalState}>
-								Reset data
+								{msg(messages.resetData)}
 							</button>
 						</div>
 					</>
 				) : (
 					<>
-						<h2>Something went wrong</h2>
-						<p>Please refresh your browser.</p>
-						<p>
-							If the issue continues after refreshing, you may need to reset the tldraw data stored
-							on your device.
-						</p>
+						<h2>{msg(messages.title)}</h2>
+						<p>{msg(messages.refreshHint)}</p>
+						<p>{msg(messages.resetHint)}</p>
 						<p>
-							<strong>Note:</strong> Resetting will erase your current project and any unsaved work.
+							<strong>{msg(messages.noteLabel)}</strong> {msg(messages.resetNote)}
 						</p>
 						{process.env.NODE_ENV !== 'production' && (
 							<p>
@@ -201,34 +249,34 @@ My browser: ${navigator.userAgent}`
 						)}
 						{shouldShowError && (
 							<>
-								Message:
+								{msg(messages.messageLabel)}
 								<h4>
 									<code>{errorMessage}</code>
 								</h4>
-								Stack trace:
+								{msg(messages.stackTraceLabel)}
 								<div className="tl-error-boundary__content__error">
 									<pre>
 										<code>{errorStack ?? errorMessage}</code>
 									</pre>
 									<button className="tlui-button" onClick={copyError}>
-										{didCopy ? 'Copied!' : 'Copy'}
+										{didCopy ? msg(messages.copied) : msg(messages.copy)}
 									</button>
 								</div>
 							</>
 						)}
 						<div className="tl-error-boundary__content__actions">
 							<button className="tlui-button" onClick={() => setShouldShowError(!shouldShowError)}>
-								{shouldShowError ? 'Hide details' : 'Show details'}
+								{shouldShowError ? msg(messages.hideDetails) : msg(messages.showDetails)}
 							</button>
 							<div className="tl-error-boundary__content__actions__group">
 								<button
 									className="tlui-button tl-error-boundary__reset"
 									onClick={() => setShouldShowResetConfirmation(true)}
 								>
-									Reset data
+									{msg(messages.resetData)}
 								</button>
 								<button className="tlui-button tl-error-boundary__refresh" onClick={refresh}>
-									Refresh page
+									{msg(messages.refreshPage)}
 								</button>
 							</div>
 						</div>

package/src/lib/config/TLI18n.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest'
+import {
+	TLI18n,
+	defaultI18n,
+	defineMessages,
+	getDeclaredMessages,
+	translateMessage,
+} from './TLI18n'
+
+const messages = defineMessages({
+	somethingWentWrong: { id: 'error.title', defaultMessage: 'Something went wrong' },
+	shapesSelected: {
+		id: 'a11y.multiple-shapes',
+		defaultMessage: '{num, plural, one {# shape selected} other {# shapes selected}}',
+	},
+	// A plain placeholder, which the regex stub below can substitute. The plural above needs a
+	// real ICU formatter, so the adapter's own handling of it is covered in packages/tldraw.
+	addedFiles: { id: 'test.added-files', defaultMessage: 'Added {total} files' },
+})
+
+function i18nWith(catalog: Record<string, string>): TLI18n {
+	return {
+		locale: 'en',
+		dir: 'ltr',
+		// Mirrors the real adapter: a message the catalog doesn't have falls back to its own
+		// English, and either way the values are substituted.
+		translate: (message, values) => {
+			const text = catalog[message.id] ?? message.defaultMessage
+			return text.replace(/\{(\w+)[^}]*\}/g, (_, name) => String(values?.[name] ?? ''))
+		},
+	}
+}
+
+describe('translateMessage', () => {
+	it('uses the translation when the catalog has one', () => {
+		const i18n = i18nWith({ 'error.title': 'Etwas ist schiefgelaufen' })
+		expect(translateMessage(i18n, messages.somethingWentWrong)).toBe('Etwas ist schiefgelaufen')
+	})
+
+	// @tldraw/editor is usable with none of tldraw's UI, so there may be no i18n at all.
+	it('falls back to the English when there is no i18n', () => {
+		expect(translateMessage(null, messages.somethingWentWrong)).toBe('Something went wrong')
+		expect(translateMessage(undefined, messages.somethingWentWrong)).toBe('Something went wrong')
+	})
+
+	// A message that hasn't been through Lokalise yet is absent from every catalog. Showing the id
+	// to someone would be worse than English.
+	it('falls back to the English when the catalog has no entry', () => {
+		expect(translateMessage(i18nWith({}), messages.somethingWentWrong)).toBe('Something went wrong')
+		expect(translateMessage(defaultI18n(), messages.somethingWentWrong)).toBe(
+			'Something went wrong'
+		)
+	})
+
+	// The adapter gets the whole message, so it can substitute into the English too. Falling back
+	// to the raw source instead put a plural message's own ICU into an upload toast.
+	it('substitutes values into the English it falls back to', () => {
+		expect(translateMessage(i18nWith({}), messages.addedFiles, { total: 3 })).toBe('Added 3 files')
+	})
+
+	it('passes values through to the translation', () => {
+		const i18n = i18nWith({ 'a11y.multiple-shapes': '{num} Formen ausgewählt' })
+		expect(translateMessage(i18n, messages.shapesSelected, { num: 3 })).toBe('3 Formen ausgewählt')
+	})
+})
+
+describe('defineMessages', () => {
+	it('returns the messages unchanged', () => {
+		const declared = { a: { id: 'x', defaultMessage: 'X' } }
+		expect(defineMessages(declared)).toEqual(declared)
+	})
+
+	// The SDK bundles no separate English catalog; a key looked up by id resolves against this.
+	it('records the English of each message it declares', () => {
+		defineMessages({
+			a: { id: 'test.declared', defaultMessage: 'Declared' },
+			b: { defaultMessage: 'No id' },
+		})
+		expect(getDeclaredMessages()).toMatchObject({
+			'test.declared': 'Declared',
+			'No id': 'No id',
+		})
+	})
+})

package/src/lib/config/TLI18n.ts

@@ -0,0 +1,172 @@
+import { atom } from '@tldraw/state'
+
+/**
+ * Values substituted into a message's ICU placeholders.
+ *
+ * @public
+ */
+export type TLI18nValues = Record<
+	string,
+	string | number | bigint | boolean | Date | null | undefined
+>
+
+/**
+ * The editor's view of the host app's translations. Lets code with no access to React context —
+ * a {@link ShapeUtil}, say — translate a string in the user's locale.
+ *
+ * @public
+ */
+export interface TLI18n {
+	locale: string
+	dir: 'ltr' | 'rtl'
+	/**
+	 * Translate `message` in the current locale, substituting `values` into its ICU placeholders.
+	 *
+	 * Takes the whole message rather than its id so an implementation can fall back to the English
+	 * and still substitute into it. A message absent from the catalog — anything not yet through
+	 * Lokalise — would otherwise have to come back as its own source text, placeholders and all.
+	 */
+	translate(message: TLI18nMessage, values?: TLI18nValues): string
+}
+
+/**
+ * Supplies a {@link TLI18n}. Called on each use rather than held as a value, so the editor reads
+ * the current locale instead of pinning whichever one was active when it was constructed.
+ *
+ * @public
+ */
+export type TLI18nAdapter = () => TLI18n
+
+/**
+ * The i18n used when the host app supplies none: every message comes back as its own English.
+ *
+ * Placeholders are left as they are, because formatting ICU needs a formatter and this package
+ * deliberately has none — it is the floor for an editor running with no translations at all.
+ *
+ * @public
+ */
+export function defaultI18n(): TLI18n {
+	return {
+		locale: 'en',
+		dir: 'ltr',
+		translate(message: TLI18nMessage) {
+			return message.defaultMessage
+		},
+	}
+}
+
+/**
+ * One translatable message: a stable `id` naming it in the catalog, and the English it falls back
+ * to. `defaultMessage` is required, because this package's strings have to read correctly with no
+ * translations loaded at all — `@tldraw/editor` can be used without any of tldraw's UI.
+ *
+ * @public
+ */
+export interface TLI18nMessage {
+	id: string
+	defaultMessage: string
+	description?: string
+}
+
+/**
+ * A message as it's written. The id is optional because a bundler plugin may supply it:
+ * `@formatjs/unplugin` with an `idInterpolationPattern` derives one from the message's own text,
+ * which is how tldraw.com does it. Everywhere downstream takes a {@link TLI18nMessage}, whose id
+ * is required, because {@link defineMessages} fills one in.
+ *
+ * @public
+ */
+export type TLI18nMessageInput = Omit<TLI18nMessage, 'id'> & { id?: string }
+
+const declaredMessages: Record<string, string> = {}
+// Bumped per `defineMessages` call, so a reader re-renders when a chunk loaded after mount — a
+// dynamically imported @tldraw/commenting, say — declares messages its labels look up by id.
+const declaredVersion = atom('declaredMessagesVersion', 0)
+let snapshot: Readonly<Record<string, string>> = {}
+let snapshotVersion = -1
+
+/**
+ * Declares messages so the extractor can find them, next to the UI that shows them — the English
+ * then lives with the code rather than in a catalog edited by hand. Call it by this name:
+ * `formatjs extract` matches the call by name, wherever it was imported from, so a wrapper under
+ * another name extracts nothing.
+ *
+ * Write the id yourself, as the SDK's own messages do — an app overrides by id, so an id has to
+ * survive a reworded English string. Leave it out only where a bundler plugin injects one; with no
+ * plugin either the English stands in, so the message still renders as itself. An id missing from
+ * a real build is caught by `pnpm i18n-extract --check`.
+ *
+ * The type parameter is `const` so each written `id` keeps its literal type, which is what lets a
+ * declared id go where a `TLUiTranslationKey` is expected — a menu item's `label`, say — instead
+ * of widening to `string` and needing a cast.
+ *
+ * For a message rendered as an element, write it inline on the `<F>` instead; the extractor reads
+ * those props directly. This is for the ones that can't be: a label the UI takes as data, and
+ * anything translated as a string through `useTranslation`.
+ *
+ * @example
+ *
+ * ```ts
+ * const messages = defineMessages({
+ * 	copy: { id: 'action.copy', defaultMessage: 'Copy' },
+ * })
+ * ```
+ *
+ * @public
+ */
+export function defineMessages<const Messages extends Record<string, TLI18nMessageInput>>(
+	msgs: Messages
+): { [K in keyof Messages]: Messages[K] & TLI18nMessage } {
+	const withIds = {} as { [K in keyof Messages]: Messages[K] & TLI18nMessage }
+	for (const key in msgs) {
+		const message = msgs[key]
+		const withId = (
+			message.id ? message : { ...message, id: message.defaultMessage }
+		) as Messages[typeof key] & TLI18nMessage
+		withIds[key] = withId
+		declaredMessages[withId.id] = withId.defaultMessage
+	}
+	declaredVersion.update((v) => v + 1)
+	return withIds
+}
+
+/**
+ * The English of every message declared so far, by id. This is the English catalog: building it
+ * from the declarations means it isn't bundled a second time as a generated file. A key looked up
+ * by id alone — a menu label, or an app calling `msg('action.copy')` — resolves against it.
+ *
+ * Declarations run as their modules load, so this is complete once the package has been imported.
+ * Reactive: read it inside `useValue` or a `computed` to pick up a module that loads later. The
+ * returned object changes identity only when something new is declared.
+ *
+ * @internal
+ */
+export function getDeclaredMessages(): Readonly<Record<string, string>> {
+	const version = declaredVersion.get()
+	if (version !== snapshotVersion) {
+		snapshot = { ...declaredMessages }
+		snapshotVersion = version
+	}
+	return snapshot
+}
+
+/**
+ * Translates `message` through an editor's i18n, falling back to its English.
+ *
+ * Takes the editor's i18n rather than reading a context, so it works in the places this package
+ * has to keep working: a `ShapeUtil` with no hooks available, or an error fallback rendered
+ * outside the editor it's reporting on.
+ *
+ * With no i18n at all the English is returned unformatted, for the reason given on
+ * {@link defaultI18n}. Every other case goes through the adapter, which does substitute.
+ *
+ * @public
+ */
+export function translateMessage(
+	i18n: TLI18n | null | undefined,
+	message: TLI18nMessage,
+	values?: TLI18nValues
+): string {
+	if (!i18n) return message.defaultMessage
+	return i18n.translate(message, values)
+}