Ensure the use of polyglot is consistent by IEvangelist · Pull Request #1559 · microsoft/aspire.dev

David Pine (IEvangelist) · 2026-08-20T19:15:49Z

Summary

This reopens #1481 (originally targeted at the now-merged release/13.5 branch) against main, with merge conflicts resolved. All commits are authored by Alistair Matthews (@alistairmatthews).

This PR:

Defines the term "polyglot" in the glossary as relating to multiple languages including C#.
Corrects use of that term throughout the content.
Links to the definition on first use of that term in each page.
Replaces "polyglot" with "non-C#", where content refers to languages other than C#.
Addresses the C# bias in code examples in the glossary (adds TypeScript examples alongside C#).

Notes on retargeting to `main`

The original branch contained a release/13.5 merge ("Resolved conflicts") that reverted unrelated content. Those merge artifacts have been excluded from this reproduction, so the diff contains only the genuine polyglot-consistency edits:

Dropped the mass revert of whats-new/aspire-13-5.mdx (its intro was rewritten on main and no longer uses the term).
Dropped stale data/pkgs/*.json churn.
Kept azure-ai-foundry-host.mdx's hosted-agent-protocol section that the artifact merge had deleted.
Kept the WithTerminal Shell/validation content and the hidden aspireSkillsRemoteFetchEnabled config row that main currently ships.

Fixes: #1480

…definition in the glossary.

…'non-C#'. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

This PR standardizes how “polyglot” is defined and used across the Aspire docs, adding a glossary definition and updating references to either link to that definition or use “non-C#” when the intent is to exclude C#.

Changes:

Adds a glossary definition for “polyglot” and updates pages to link to it on first use.
Replaces “polyglot” with “non-C#” where the content is specifically about non-C# AppHosts/APIs.
Expands glossary examples to include TypeScript alongside C# (via language pivots).

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/frontend/src/content/docs/whats-new/aspire-13-4.mdx	Replaces “polyglot” with “non-C#” in 13.4 release notes where referring to non-C# AppHosts/SDK layout.
src/frontend/src/content/docs/whats-new/aspire-13-3.mdx	Links first use of “polyglot” to glossary (but one spot still uses it to mean “non-C#”).
src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md	Updates feature-flag descriptions to say “non-C#” where appropriate.
src/frontend/src/content/docs/reference/cli/configuration.mdx	Adjusts example title to remove “polyglot” wording.
src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx	Replaces “polyglot AppHost” with “non-C# AppHost” in failure-diagnostics text.
src/frontend/src/content/docs/ja/extensibility/multi-language-integration-authoring.mdx	Adds an in-page definition/link clarifying “polyglot” in the Japanese translation.
src/frontend/src/content/docs/integrations/frameworks/go/go-host.mdx	Links “polyglot” to glossary when referring to the Go language feature flag.
src/frontend/src/content/docs/integrations/devtools/flagd/flagd-get-started.mdx	Links “polyglot” to glossary in OFREP note.
src/frontend/src/content/docs/integrations/devtools/flagd/flagd-connect.mdx	Links “polyglot” to glossary in OFREP section.
src/frontend/src/content/docs/integrations/devtools/dev-tunnels.mdx	Replaces “polyglot” with “non-C#” in a TypeScript API limitation note.
src/frontend/src/content/docs/integrations/databases/surrealdb/surrealdb-host.mdx	Replaces “polyglot TypeScript AppHost” with “non-C# TypeScript AppHost”.
src/frontend/src/content/docs/integrations/databases/ravendb/ravendb-host.mdx	Replaces “polyglot TypeScript AppHost” with “non-C# TypeScript AppHost”.
src/frontend/src/content/docs/integrations/cloud/azure/azure-virtual-network.mdx	Links “polyglot” to glossary for “polyglot-friendly helper” phrasing.
src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-host.mdx	Links “polyglot” to glossary for “polyglot-friendly helper” phrasing.
src/frontend/src/content/docs/integrations/cloud/azure/azure-postgresql/azure-postgresql-host.mdx	Links “polyglot” to glossary for “polyglot-friendly helper” phrasing.
src/frontend/src/content/docs/integrations/cloud/azure/azure-log-analytics.mdx	Links “polyglot” to glossary for “polyglot-friendly helper” phrasing.
src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx	Links “polyglot” to glossary for “polyglot-friendly helper” phrasing.
src/frontend/src/content/docs/get-started/glossary.mdx	Adds “Polyglot” glossary entry and adds TypeScript pivots alongside C# examples.
src/frontend/src/content/docs/get-started/faq.mdx	Links “polyglot” to glossary in the AppHost overview answer.
src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx	Links “polyglot” to glossary in the intro sentence.
src/frontend/src/content/docs/get-started/add-aspire-existing-app.mdx	Links “polyglot” to glossary in the file-based AppHost description.
src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx	Links “polyglot” to glossary in ATS override tag description.
src/frontend/src/content/docs/app-host/with-terminal.mdx	Replaces “polyglot API” with “non-C# API” in a TypeScript note.
src/frontend/src/content/docs/app-host/executable-resources.mdx	Replaces “polyglot AppHost” with “non-C# AppHost” in 13.3 environment API note.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.


+### Polyglot
+
+In this repository, **polyglot** means relating to code and applications written in multiple languages, including TypeScript, C#, Python, Go, Java, and Rust. Aspire supports polyglot code in AppHosts, generated SDKs, others projects, and related tooling.


Adam Ratzman (adamint) · 2026-08-20T19:50:59Z

 ### Unified `withEnvironment` API

-Aspire 13.3 introduces a unified `withEnvironment(name, value)` API for polyglot AppHosts (TypeScript, Java, Python, Go, Rust). The public TypeScript API accepts plain strings, reference expressions, endpoint references, parameter resources, supported resources that expose connection strings, expression values, and awaitable forms of supported values:
+Aspire 13.3 introduces a unified `withEnvironment(name, value)` API for [polyglot](/get-started/glossary/#polyglot) AppHosts (TypeScript, Java, Python, Go, Rust). The public TypeScript API accepts plain strings, reference expressions, endpoint references, parameter resources, supported resources that expose connection strings, expression values, and awaitable forms of supported values:


This same distinction also applies to integrations/frameworks/go/go-host.mdx: the flag enables one Go AppHost language, so calling it the Go “polyglot” feature flag conflicts with the new definition.


-   ```bash title="Enable global polyglot Go support"
+   ```bash title="Enable global Go support"
   aspire config set features:experimentalPolyglot:go true


aspire-repo-bot · 2026-08-20T19:35:37Z

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1559. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.

Adam Ratzman (adamint) · 2026-08-20T19:50:59Z

-| `features.experimentalPolyglot:python`    | `features.experimentalPolyglot:python`    | Enable or disable experimental Python language support for polyglot Aspire applications.                                        |
-| `features.experimentalPolyglot:rust`      | `features.experimentalPolyglot:rust`      | Enable or disable experimental Rust language support for polyglot Aspire applications.                                          |
-| `features.polyglotIntegrationFilterEnabled` | `features.polyglotIntegrationFilterEnabled` | Enable or disable filtering `aspire add`, `aspire integration list`, and `aspire integration search` results to only integrations compatible with a non-C# (polyglot) AppHost. Disabled by default because remote NuGet feeds don't reliably answer the `tags:polyglot` query used to build the compatibility allow-list. |
+| `features.experimentalPolyglot:go`        | `features.experimentalPolyglot:go`        | Enable or disable experimental Go language support for non-C# Aspire applications.           |


I don’t think “non-C# Aspire applications” is quite accurate here. These flags gate whether the CLI discovers the corresponding experimental AppHost language, not whether an application contains Go/Java/Python/Rust workloads. Could we say “experimental Go AppHost support” (and equivalent for the other rows)?

Adam Ratzman (adamint) · 2026-08-20T19:50:59Z

+```typescript title="apphost.mts"
+const db = await builder.addPostgres("db");
+await builder.addProject("api", "../Api/Api.csproj")
+    .withReference(db);  // API now has DATABASE connection info injected


Could we update the surrounding heading/prose to WithReference()/withReference() now that this adds a TypeScript pivot? WaitFor does this already, but WithReference, WaitForCompletion, and WaitForStart still describe only the C# casing.

Alistair Matthews (alistairmatthews) and others added 6 commits August 20, 2026 14:09

Ensured the use of polyglot is consistent and linked first uses to a …

e06edf9

…definition in the glossary.

Addressed feedback from @Copilot.

93090c9

Added TypeScript examples to all C# examples in the Glossary.

9d00820

Amended the definition of polyglot in response to @adamint's feedback.

c9acb96

Redefined polyglot as relating to mulitple languages including C#.

427f29a

Where 'polyglot' was used to mean any language but C#, replaced with …

ad4bc88

…'non-C#'. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI lite review requested due to automatic review settings August 20, 2026 19:15

David Pine (IEvangelist) requested review from Eric Erhardt (eerhardt) and Mitch Denny (mitchdenny) as code owners August 20, 2026 19:15

Copilot AI reviewed Aug 20, 2026

View reviewed changes

Adam Ratzman (adamint) reviewed Aug 20, 2026

View reviewed changes

Copilot started reviewing on behalf of David Pine (IEvangelist) August 20, 2026 22:02 View session

Navigation Menu

Uh oh!

Ensure the use of polyglot is consistent - #1559

Ensure the use of polyglot is consistent#1559
David Pine (IEvangelist) wants to merge 6 commits into
mainfrom
dapine/polyglot-consistency

David Pine (IEvangelist) commented Aug 20, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Adam Ratzman (adamint) Aug 20, 2026

Uh oh!

aspire-repo-bot Bot commented Aug 20, 2026

Uh oh!

Adam Ratzman (adamint) Aug 20, 2026

Uh oh!

Adam Ratzman (adamint) Aug 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		### Polyglot

		In this repository, polyglot means relating to code and applications written in multiple languages, including TypeScript, C#, Python, Go, Java, and Rust. Aspire supports polyglot code in AppHosts, generated SDKs, others projects, and related tooling.

Uh oh!

Conversation

David Pine (IEvangelist) commented Aug 20, 2026

Summary

Notes on retargeting to main

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Adam Ratzman (adamint) Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

aspire-repo-bot Bot commented Aug 20, 2026

Frontend HTML artifact ready

Uh oh!

Adam Ratzman (adamint) Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

Adam Ratzman (adamint) Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Notes on retargeting to `main`