diff --git a/site/src/content/docs/how-to/i18n-override-translations.mdx b/site/src/content/docs/how-to/i18n-override-translations.mdx
index ec4fc64f..ce3b4bbd 100644
--- a/site/src/content/docs/how-to/i18n-override-translations.mdx
+++ b/site/src/content/docs/how-to/i18n-override-translations.mdx
@@ -59,7 +59,7 @@ Use <DocsLink slug="reference/media-text">`<media-text>`</DocsLink> for static c
 
 ```html
 <media-i18n lang="es">
-  <media-text key="Play"></media-text>
+  <media-text>Play</media-text>
 </media-i18n>
 ```
 
diff --git a/site/src/content/docs/reference/media-i18n.mdx b/site/src/content/docs/reference/media-i18n.mdx
index b76873f6..9a25caaa 100644
--- a/site/src/content/docs/reference/media-i18n.mdx
+++ b/site/src/content/docs/reference/media-i18n.mdx
@@ -22,7 +22,7 @@ Register locale strings with <DocsLink slug="reference/register-i18n">`registerI
 </script>
 
 <media-i18n lang="es">
-  <media-text key="Play"></media-text>
+  <media-text>Play</media-text>
 </media-i18n>
 ```
 
@@ -34,7 +34,7 @@ Register locale strings with <DocsLink slug="reference/register-i18n">`registerI
 
 ## Related
 
-- <DocsLink slug="reference/media-text">`<media-text>`</DocsLink> — renders a translated string by key
+- <DocsLink slug="reference/media-text">`<media-text>`</DocsLink> — renders translated text content
 - <DocsLink slug="how-to/i18n-register-locale">Register a custom locale</DocsLink>
 
 </FrameworkCase>
diff --git a/site/src/content/docs/reference/media-text.mdx b/site/src/content/docs/reference/media-text.mdx
index bd7cf1d4..48c7e3de 100644
--- a/site/src/content/docs/reference/media-text.mdx
+++ b/site/src/content/docs/reference/media-text.mdx
@@ -8,19 +8,17 @@ import FrameworkCase from "@/components/docs/FrameworkCase.astro";
 
 <FrameworkCase frameworks={["html"]}>
 
-`<media-text>` renders the translated value for a registry phrase inside a <DocsLink slug="reference/media-i18n">`<media-i18n>`</DocsLink> (or any ancestor with the i18n provider mixin). Use it for standalone labels, tooltips, or demos — skin controls resolve phrases internally.
+`<media-text>` renders the translated value for its text content inside a <DocsLink slug="reference/media-i18n">`<media-i18n>`</DocsLink> (or any ancestor with the i18n provider mixin). Use it for standalone labels, tooltips, or demos — skin controls resolve phrases internally.
 
 ```html
 <media-i18n lang="ja">
-  <media-text key="Play"></media-text>
+  <media-text>Play</media-text>
 </media-i18n>
 ```
 
-## Attributes
+## Text content
 
-| Attribute | Description |
-| --- | --- |
-| `key` | English translation phrase (`Play`, `Pause`, `{duration} remaining`, …). |
+The initial text content is the English translation phrase (`Play`, `Pause`, `{duration} remaining`, …). If the phrase is not registered for the active locale, `<media-text>` keeps the original text.
 
 Parametric phrases are not yet supported on `<media-text>` — use `createTranslator` in script for interpolated strings.