framer · tom-james-watson · Dec 3, 2024 · Dec 3, 2024 · Dec 6, 2024
diff --git a/package-lock.json b/package-lock.json
diff --git a/plugins/localization-import-export/.gitignore b/plugins/localization-import-export/.gitignore
@@ -0,0 +1,33 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+
+/node_modules
+/.pnp
+.pnp.js
+.yarn
+
+# misc
+
+.DS_Store
+\*.pem
+
+# files
+
+my-plugin
+dev-plugin
+dist
+
+# debug
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log\*
+
+# local env files
+
+.env\*.local
+
+# Packed plugin
+
+plugin.zip
diff --git a/plugins/localization-import-export/README.md b/plugins/localization-import-export/README.md
@@ -0,0 +1,3 @@
+# Localization Import & Export
+
+Import and export your Framer localizations using the common XLIFF format.
diff --git a/plugins/localization-import-export/eslint.config.js b/plugins/localization-import-export/eslint.config.js
@@ -0,0 +1,25 @@
+import js from "@eslint/js"
+import globals from "globals"
+import reactHooks from "eslint-plugin-react-hooks"
+import reactRefresh from "eslint-plugin-react-refresh"
+import tseslint from "typescript-eslint"
+
+export default tseslint.config(
+    { ignores: ["dist"] },
+    {
+        extends: [js.configs.recommended, ...tseslint.configs.recommended],
+        files: ["**/*.{ts,tsx}"],
+        languageOptions: {
+            ecmaVersion: 2022,
+            globals: globals.browser,
+        },
+        plugins: {
+            "react-hooks": reactHooks,
+            "react-refresh": reactRefresh,
+        },
+        rules: {
+            ...reactHooks.configs.recommended.rules,
+            "react-refresh/only-export-components": ["warn", { allowConstantExport: true }],
+        },
+    }
+)
diff --git a/plugins/localization-import-export/framer.json b/plugins/localization-import-export/framer.json
@@ -0,0 +1,6 @@
+{
+    "id": "fc87df",
+    "name": "Localization Import & Export",
+    "modes": ["localization"],
+    "icon": "/icon.svg"
+}
diff --git a/plugins/localization-import-export/index.html b/plugins/localization-import-export/index.html
@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+  <html lang="en">
+    <head>
+      <meta charset="UTF-8" />
+      <link rel="icon" type="image/svg+xml" href="/icon.svg" />
+      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+      <title>Localization Import Export</title>
+    </head>
+    <body>
+      <div id="root"></div>
+      <script type="module" src="/src/main.tsx"></script>
+    </body>
+  </html>
+
diff --git a/plugins/localization-import-export/package.json b/plugins/localization-import-export/package.json
@@ -0,0 +1,34 @@
+{
+  "name": "localization-import-export",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "preview": "vite preview",
+    "pack": "npx framer-plugin-tools@latest pack"
+  },
+  "dependencies": {
+    "framer-plugin": "^2.1.0-beta.0",
+    "react": "^18",
+    "react-dom": "^18",
+    "vite-plugin-mkcert": "^1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9",
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
+    "@vitejs/plugin-react": "^4.3.1",
+    "@vitejs/plugin-react-swc": "^3",
+    "eslint": "^9.9.0",
+    "eslint-plugin-react-hooks": "^5.1.0-rc.0",
+    "eslint-plugin-react-refresh": "^0.4.9",
+    "globals": "^15.9.0",
+    "typescript": "^5.3",
+    "typescript-eslint": "^8.0.1",
+    "vite": "^5",
+    "vite-plugin-framer": "^1"
+  }
+}
diff --git a/plugins/localization-import-export/public/icon.svg b/plugins/localization-import-export/public/icon.svg
diff --git a/plugins/localization-import-export/src/App.css b/plugins/localization-import-export/src/App.css
@@ -0,0 +1,12 @@
+main {
+    display: flex;
+    flex-direction: column;
+    align-items: start;
+    padding: 0 15px 15px 15px;
+    height: 100%;
+    gap: 15px;
+}
+
+select {
+    width: 100%;
+}
diff --git a/plugins/localization-import-export/src/App.tsx b/plugins/localization-import-export/src/App.tsx
@@ -0,0 +1,103 @@
+import { framer, Locale } from "framer-plugin"
+import { useEffect, useState } from "react"
+import "./App.css"
+import { downloadBlob, importFileAsText } from "./files"
+import { createLocalizationsUpdateFromXliff, generateXliff, parseXliff } from "./xliff"
+
+framer.showUI({
+    width: 300,
+    height: 152,
+})
+
+async function importXliff() {
+    importFileAsText(".xlf,.xliff", async (xliffText: string) => {
+        try {
+            const locales = await framer.unstable_getLocales()
+
+            const { xliff, targetLocale } = parseXliff(xliffText, locales)
+            const update = createLocalizationsUpdateFromXliff(xliff, targetLocale)
+
+            const result = await framer.unstable_setLocalizedValues(update)
+
+            if (result.errors.length > 0) {
+                throw new Error(`Import errors: ${result.errors.map(error => error.error).join(", ")}`)
+            }
+
+            framer.notify(`Successfully imported localizations for ${targetLocale.name}`)
+        } catch (error) {
+            console.error(error)
+            framer.notify(error instanceof Error ? error.message : "Error importing XLIFF file", { variant: "error" })
+        }
+    })
+}
+
+async function exportXliff(defaultLocale: Locale, targetLocale: Locale) {
+    const filename = `localizations_${targetLocale.code}.xlf`
+
+    try {
+        const sources = await framer.unstable_getLocalizationSources()
+        const xliff = generateXliff(defaultLocale, targetLocale, sources)
+        downloadBlob(xliff, filename, "application/x-xliff+xml")
+
+        framer.notify(`Successfully exported ${filename}`)
+    } catch (error) {
+        console.error(error)
+        framer.notify(`Error exporting ${filename}`, { variant: "error" })
+    }
+}
+
+export function App() {
+    const [selectedLocaleId, setSelectedLocaleId] = useState<string>("")
+    const [locales, setLocales] = useState<readonly Locale[]>([])
+    const [defaultLocale, setDefaultLocale] = useState<Locale | null>(null)
+
+    useEffect(() => {
+        async function loadLocales() {
+            const allLocales = await framer.unstable_getLocales()
+            const defaultLocale = await framer.unstable_getDefaultLocale()
+            setLocales(allLocales)
+            setDefaultLocale(defaultLocale)
+
+            const firstLocale = allLocales[0]
+            if (!firstLocale) return
+            setSelectedLocaleId(firstLocale.id)
+        }
+
+        loadLocales()
+    }, [])
+
+    async function handleExport() {
+        if (!selectedLocaleId || !defaultLocale) return
+
+        const targetLocale = locales.find(locale => locale.id === selectedLocaleId)
+        if (!targetLocale) return
+
+        exportXliff(defaultLocale, targetLocale)
+    }
+
+    return (
+        <main>
+            <button className="framer-button-primary" onClick={importXliff}>
+                Import XLIFF
+            </button>
+
+            <hr />
+
+            <select
+                value={selectedLocaleId}
+                onChange={e => setSelectedLocaleId(e.target.value)}
+                disabled={!selectedLocaleId}
+            >
+                {locales.map(locale => (
+                    <option key={locale.id} value={locale.id}>
+                        {locale.name} ({locale.code})
+                    </option>
+                ))}
+            </select>
+
+            <button className="framer-button-primary" onClick={handleExport} disabled={!selectedLocaleId}>
+                Export XLIFF
+            </button>
+        </main>
+    )
+}
diff --git a/plugins/localization-import-export/src/files.ts b/plugins/localization-import-export/src/files.ts
@@ -0,0 +1,27 @@
+export function downloadBlob(value: string, filename: string, type: string) {
+    const blob = new Blob([value], { type })
+    const url = URL.createObjectURL(blob)
+
+    const a = document.createElement("a")
+    a.href = url
+    a.download = filename
+
+    a.click()
+    URL.revokeObjectURL(url)
+}
+
+export function importFileAsText(accept: string, handleImport: (file: string) => Promise<void>) {
+    const input = document.createElement("input")
+    input.type = "file"
+    input.accept = accept
+
+    input.onchange = async event => {
+        const file = (event.target as HTMLInputElement).files?.[0]
+        if (!file) return
+        const fileText = await file.text()
+
+        void handleImport(fileText)
+    }
+
+    input.click()
+}
diff --git a/plugins/localization-import-export/src/main.tsx b/plugins/localization-import-export/src/main.tsx
@@ -0,0 +1,14 @@
+import "framer-plugin/framer.css"
+
+import React from "react"
+import ReactDOM from "react-dom/client"
+import { App } from "./App.tsx"
+
+const root = document.getElementById("root")
+if (!root) throw new Error("Root element not found")
+
+ReactDOM.createRoot(root).render(
+    <React.StrictMode>
+        <App />
+    </React.StrictMode>
+)
diff --git a/plugins/localization-import-export/src/vite-env.d.ts b/plugins/localization-import-export/src/vite-env.d.ts
@@ -0,0 +1 @@
+/// <reference types="vite/client" />
diff --git a/plugins/localization-import-export/src/xliff.ts b/plugins/localization-import-export/src/xliff.ts
@@ -0,0 +1,78 @@
+import { Locale, LocalizationSource, LocalizationSourceId, LocalizedValuesUpdate } from "framer-plugin"
+import "./App.css"
+
+function escapeXml(unsafe: string): string {
+    return unsafe
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;")
+}
+
+function generateUnit(source: LocalizationSource, targetLocale: Locale) {
+    // TODO: expose localization's status to be able to set this correctly
+    // See http://docs.oasis-open.org/xliff/xliff-core/v2.0/os/xliff-core-v2.0-os.html#state
+    const state = source.valueLocalized[targetLocale.id]?.value ? "final" : `initial`
+
+    const sourceValue = escapeXml(source.value)
+    const targetValue = escapeXml(source.valueLocalized[targetLocale.id]?.value || "")
+
+    return `        <unit id="${source.id}">
+            <notes>
+                <note category="type">${source.type}</note>
+            </notes>
+            <segment>
+                <source>${sourceValue}</source>
+                <target state="${state}">${targetValue}</target>
+            </segment>
+        </unit>`
+}
+
+export function generateXliff(defaultLocale: Locale, targetLocale: Locale, sources: readonly LocalizationSource[]) {
+    const units = sources.map(source => generateUnit(source, targetLocale)).join("\n")
+
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<xliff xmlns="urn:oasis:names:tc:xliff:document:2.0" version="2.0" srcLang="${defaultLocale.code}" trgLang="${targetLocale.code}">
+    <file id="${targetLocale.id}" srcLang="${defaultLocale.code}" trgLang="${targetLocale.code}">
+${units}
+    </file>
+</xliff>`
+}
+
+export function parseXliff(xliffText: string, locales: readonly Locale[]): { xliff: Document; targetLocale: Locale } {
+    const parser = new DOMParser()
+    const xliff = parser.parseFromString(xliffText, "text/xml")
+
+    const file = xliff.querySelector("file")
+    if (!file) throw new Error("No file element found in XLIFF")
+
+    const targetLanguage = file.getAttribute("trgLang")
+    if (!targetLanguage) throw new Error("No target language found in XLIFF")
+
+    const targetLocale = locales.find(locale => locale.code === targetLanguage)
+    if (!targetLocale) {
+        throw new Error(`No locale found for language code: ${targetLanguage}`)
+    }
+
+    return { xliff: xliff, targetLocale }
+}
+
+export function createLocalizationsUpdateFromXliff(
+    xliffDocument: Document,
+    targetLocale: Locale
+): Record<LocalizationSourceId, LocalizedValuesUpdate> {
+    const update: Record<LocalizationSourceId, LocalizedValuesUpdate> = {}
+
+    const units = xliffDocument.querySelectorAll("unit")
+    units.forEach(unit => {
+        const id = unit.getAttribute("id")
+        const target = unit.querySelector("target")?.textContent
+        if (!id || !target) return
+
+        const targetValue = target ? target : null
+        update[id] = { [targetLocale.id]: targetValue }
+    })
+
+    return update
+}
diff --git a/plugins/localization-import-export/tsconfig.json b/plugins/localization-import-export/tsconfig.json
@@ -0,0 +1,23 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "useDefineForClassFields": true,
+        "lib": ["ES2022", "DOM", "DOM.Iterable"],
+        "module": "ES2022",
+
+        /* Bundler mode */
+        "moduleResolution": "bundler",
+        "allowImportingTsExtensions": true,
+        "resolveJsonModule": true,
+        "isolatedModules": true,
+        "noEmit": true,
+        "jsx": "react-jsx",
+
+        /* Linting */
+        "strict": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "noFallthroughCasesInSwitch": true
+    },
+    "include": ["src"]
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Localization Import & Export

		Import and export your Framer localizations using the common XLIFF format.