feat: Add dual language selector for AI Transport guides

[GregHolmes]

Summary

Adds dual language selection for AI Transport guide pages, allowing users to independently choose Client (frontend) and Agent (backend) languages for code examples.

Changes

• Dual language selector UI: Two dropdowns ("Client" and "Agent") replace the single language selector on AI Transport guide pages
• URL param support: ?fe_lang=xxx&be_lang=yyy for bookmarking and sharing specific language combinations
• Navigation preservation: Language params persist when navigating between guide pages
• Code block prefixes: MDX files use fe_ and be_ prefixes (e.g., fe_javascript, be_python) to distinguish frontend vs backend code
• aiTransport languages: javascript, python, swift, java with SDK versions

Supported languages

• Client: JavaScript, Swift, Java
• Agent: JavaScript, Python, Java

Dependencies

• Requires @ably/ui@17.13.1-dev.c839343a (or later) with fe_/be_ prefix support in CodeSnippet
• Also removes stale CookieMessage CSS import that was breaking builds with newer ably-ui versions

Summary by CodeRabbit

• New Features

  • Dual-language selection supporting client and agent language preferences
  • Expanded multi-language code examples for Anthropic integration guides
  • Updated language support versions for AI Transport

• Documentation

  • Enhanced guides with per-language setup instructions and implementations for JavaScript, Python, Java, and Swift

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

This pull request implements dual-language support for Client and Agent code blocks across the documentation platform. Changes introduce language selection infrastructure, context providers, and conditional rendering logic, along with updated language data and comprehensive guide documentation with per-language implementations.

Changes

Cohort / File(s)	Summary
Language Selection Infrastructure src/components/Layout/LanguageSelector.tsx	Refactored to support dual-language mode with new DualLanguageSelector and DualLanguageDropdown components alongside existing SingleLanguageSelector. Adds logic to determine rendering mode based on activePage.isDualLanguage and updates URL query parameters for client_lang and agent_lang.
Context & Provider src/contexts/layout-context.tsx	Added CLIENT_LANGUAGES and AGENT_LANGUAGES arrays, isDualLanguagePath detection function, and helpers for deriving clientLanguage, agentLanguage, and isDualLanguage. Extended LayoutContext to include these fields in activePage object.
Navigation Types & Utilities src/components/Layout/utils/nav.ts	Extended ActivePage type with optional clientLanguage, agentLanguage, and isDualLanguage fields to support dual-language metadata.
Sidebar Navigation src/components/Layout/LeftSidebar.tsx	Added buildLinkWithParams helper to construct links with appropriate language query parameters based on dual-language support. Updated link generation to preserve client_lang/agent_lang for dual-language targets.
MDX Code Block Handling src/components/Layout/MDXWrapper.tsx	Enhanced code-block language detection to support client_ and agent_ prefixed languages and dual-language filtering. Extended SDKContextType to allow SDKType | undefined. Adds detection and conditional rendering for dual-language code blocks.
Conditional Content Rendering src/components/Layout/mdx/If.tsx	Added three optional props (client_lang, agent_lang, client_or_agent_lang) to enable per-language content filtering. Extended activePage to expose clientLanguage and agentLanguage.
Language Selector Display src/components/Layout/mdx/PageHeader.tsx	Updated showLanguageSelector logic to always display for dual-language pages via activePage.isDualLanguage.
Language & SDK Data src/data/languages/languageData.ts	Updated JavaScript version in aiTransport from 2.11 to 2.16 and added Swift 1.2 entry.
Navigation Structure src/data/nav/aitransport.ts	Restructured Guides section to group token-streaming entries by provider (OpenAI, Anthropic, LangGraph, Vercel AI SDK) with nested "Message per response" and "Message per token" items.
Guide Documentation src/pages/docs/guides/ai-transport/anthropic-message-per-response.mdx, anthropic-message-per-token.mdx	Significantly expanded guides with multi-language conditional sections (JavaScript, Python, Java, Swift), separate agent and client code blocks, and step-by-step implementations with language-specific setup and event handling.
Dependencies package.json	Updated @ably/ui from 17.13.2 to 17.13.2-dev.aa83caf92f.
Test Mocks src/components/Layout/LeftSidebar.test.tsx	Added isDualLanguagePath to layout context mock.

Sequence Diagram

sequenceDiagram
    participant User
    participant LanguageSelector
    participant LayoutContext
    participant LeftSidebar
    participant MDXWrapper
    participant CodeBlock as If/CodeBlock
    
    User->>LanguageSelector: Select client language
    LanguageSelector->>LanguageSelector: Check activePage.isDualLanguage
    alt isDualLanguage true
        LanguageSelector->>LanguageSelector: Render DualLanguageSelector
        LanguageSelector->>LanguageSelector: Update client_lang/agent_lang params
    else isDualLanguage false
        LanguageSelector->>LanguageSelector: Render SingleLanguageSelector
        LanguageSelector->>LanguageSelector: Update lang param
    end
    
    LanguageSelector->>LayoutContext: Update URL query params
    LayoutContext->>LayoutContext: determineClientLanguage/determineAgentLanguage
    LayoutContext->>LayoutContext: Set clientLanguage & agentLanguage in activePage
    
    LeftSidebar->>LayoutContext: Read isDualLanguagePath
    LeftSidebar->>LeftSidebar: buildLinkWithParams preserves lang params
    
    MDXWrapper->>MDXWrapper: Detect client_/agent_ prefixed languages
    MDXWrapper->>MDXWrapper: Filter code blocks based on clientLanguage/agentLanguage
    MDXWrapper->>CodeBlock: Pass language selection context
    
    CodeBlock->>CodeBlock: Evaluate If conditions (client_lang, agent_lang, etc.)
    CodeBlock->>User: Render filtered content for selected language

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Poem

🐰 Dual tongues now dance in harmony,
Client whispers, Agent speaks free,
Language selectors bloom and split,
Context flows—dual-language knit!
Guides expand in every tongue, 🌍✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: introducing a dual language selector feature for AI Transport guides, which is the core objective of this PR.
Linked Issues check	✅ Passed	The PR comprehensively addresses AIT-108 by implementing dual language selection (Client/Agent) for framework/language combinations in AI Transport guides with UI, routing, and content updates.
Out of Scope Changes check	✅ Passed	All changes are within scope of AIT-108: dual language selector implementation, language-aware navigation, MDX updates for client/agent code blocks, and supporting infrastructure.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch AIT-108-Framework-language-feature-combos-investigate-and-design-navigation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[mschristensen]

I haven't reviewed the code in detail, I will leave that to someone in the docs/deved team. But from a UX perspective, I really like the approach and I am happy with this :)

[GregHolmes]

This branch is heavily dependant on https://github.com/ably/ably-ui/pull/1060. Which I need the devex web team to review. I'm very sorry but you're not going to be able to view the deployment as it stands as I've made changes to the ably-ui.

Note: I've asked April to make me a early release candidate version for ably-ui that I can use in this branch. I'll update with a new comment when it happens.

I've added quite a few people to the reviews. I think I'd like to recommend what each person reviews!

@m-hulbert Could I please have you review this from the docs perspective?
@lawrence-forooghian and @ttypic Could you please review the JS/Swift/Java/Python code snippets that these two guides compile into? I think I've got them where they should be but would be happier with some experts in the languages checking them out.
@kennethkalmer and @matt423 Would it be possible for you to first review https://github.com/ably/ably-ui/pull/1060 as this branch won't work without those changes. Then hopefully could you review the code in this PR following that?

Let me know if you have any questions.

[GregHolmes]

I've now moved the ably-ui code over to the new package in website repo: https://github.com/ably/website/pull/7827

[lawrence-forooghian]

I'm gonna see if the skill from #3192 can be helpful here

[matt423]

Could we auto expand these to help with visibility? Like we do for spaces

[matt423]

client_lang and clientLanguage are essentially the same variable names(just shorthand difference). Would be good to rename to clearly separate what they do. Echo previous comment about using camelCase

[m-hulbert]

This is great, Greg. I have a few comments for consideration though:

• I'm not sure on the text within the page header that we're using for 'agent' and 'client' - might be worth a quick screenshot and DM to design.
• I think we need to introduce a label on the codeblocks that denotes whether it's related to the agent or client.

These two are maybe conflicting depending on how we solve them, but worth your thoughts:

• Should we go generic for the params with something like lang and lang2 so that we don't force ourselves into agent/client terminology and can reuse this for FE/BE in other places (thinking auth as the most likely culprit)?
• Obviously if we do this, we need a way per page (in frontmatter), or per section (in data files) to label what these mean on the page. That also impacts the 2nd point I made about labelling on the blocks themselves.
• Related to both of the above, in the example of auth we'd need to see how this interacts with the REST/realtime switcher too.

[GregHolmes]

This is great, Greg. I have a few comments for consideration though:

• I'm not sure on the text within the page header that we're using for 'agent' and 'client' - might be worth a quick screenshot and DM to design.
• I think we need to introduce a label on the codeblocks that denotes whether it's related to the agent or client.

These two are maybe conflicting depending on how we solve them, but worth your thoughts:

• Should we go generic for the params with something like lang and lang2 so that we don't force ourselves into agent/client terminology and can reuse this for FE/BE in other places (thinking auth as the most likely culprit)?
• Obviously if we do this, we need a way per page (in frontmatter), or per section (in data files) to label what these mean on the page. That also impacts the 2nd point I made about labelling on the blocks themselves.
• Related to both of the above, in the example of auth we'd need to see how this interacts with the REST/realtime switcher too.

Thanks Mark,

I think if we go with something generic like lang and lang2 we're going to have potential issues in two places:
1 - The developers producing guides will need to try to figure out what is what.
2 - The url params just look odd, so anyone wanting to go direct to a link may get confused.

I think from a backend (docs ) perspective, does it really matter if we have two, (possibly three with auth) options of functionality?

These are what I can see as possibilities

Option A: Keep specific (agent_lang / client_lang)
• URL: ?agent_lang=javascript&client_lang=swift
• Code blocks: agent_javascript, client_swift
• MDX:
• Pros: Clear semantics, simple, works now
• Cons: Not reusable for auth or other page types

Option B: Generic (lang1 / lang2) with frontmatter labels
• URL: ?lang1=javascript&lang2=swift
• Code blocks: lang1_javascript, lang2_swift
• MDX:
• Labels defined per-page in frontmatter (e.g. lang1.label: "Agent", lang2.label: "Client")
• Pros: Reusable across all page types (AI Transport, auth, etc.)
• Cons: More abstract, harder to read in MDX, every dual-language page needs frontmatter config

Option C: Hybrid (recommended)
• Ship agent_lang / client_lang now for AI Transport
• Add new specific pairs later when needed (e.g. frontend / backend for auth)
• Extract a shared abstraction once 2-3 concrete use cases exist
• Pros: Pragmatic, low risk, ships now
• Cons: Multiple conventions to maintain short-term

I think personally C is where I'm leaning towards but it won't be me maintaining it so I'd need people to decide what's best for them to maintain down the line.