Trados Studio 2026 Release

.github/copilot-instructions.md

@@ -0,0 +1,36 @@
+# Copilot Instructions for Trados Studio API Documentation
+
+## Project Overview
+This is the **Trados Studio Public API documentation** repository, built with [DocFX](https://dotnet.github.io/docfx/). Content is authored in Markdown and structured via `toc.yml` files.
+
+## Repository Structure
+- `articles/` — Getting started guides, hints, and tips for Trados Studio plug-in development
+- `apiconcepts/` — API concepts, guidelines, and API references (batch tasks, core, file type support, integration, project automation, terminology, translation memory, verification)
+- `api/` — Auto-generated API reference metadata
+- `Plugins/TradosStudioDocsPlugin/` — Custom DocFX plugin
+- `RWSTemplate/` — DocFX site template
+- `docfx.json` — DocFX configuration
+
+## Writing Guidelines
+- **Use active voice** over passive voice.
+- **Use precise, strong verbs** — avoid weak verbs like "is", "occur", "happen".
+- Write clear, concise sentences aimed at developers.
+- Follow the detailed conventions in `writing_guidelines.md`.
+
+## Variable Constructs
+Use `Var:VariableName` to reference product names and versions. Do **not** hardcode product names. Available variables:
+- `Var:ProductName` — e.g., Trados Studio
+- `Var:ProductNameWithEdition` — e.g., Trados Studio 2021
+- `Var:ProductVersion` — e.g., Studio16
+- `Var:VersionNumber` — e.g., 16
+- `Var:VisualStudioEdition` — e.g., the compatible Visual Studio edition
+
+## Content Conventions
+- New Markdown files must have a corresponding entry in the relevant `toc.yml`.
+- Follow existing file and folder naming patterns (lowercase, descriptive names).
+- Code samples should target the Trados Studio public API and use C#.
+- Keep documentation consistent with existing articles in tone and structure.
+
+## DocFX
+- Build locally with `docfx docfx.json` to verify changes.
+- The `docfx.json` file defines metadata sources (DLLs) and build configuration — avoid modifying unless necessary.

.github/workflows/release.yml

@@ -26,11 +26,11 @@ jobs:
       ProductVersion: Studio18
       VersionNumber: 18
       VisualStudioEdition: 'Microsoft Visual Studio 2022'
-      PluginPackedPath : '%AppData%\Trados\Trados Studio\18\Plugins\Packages\'
-      PluginUnpackedPath: '%AppData%\Trados\Trados Studio\18\Plugins\Unpacked\'
-      InstallationFolder: 'C:\Program Files (x86)\Trados\Trados Studio\Studio18'
-      DefaultProjectsFolder: 'C:\Users\UserName\Documents\Studio 2024\Projects'
-      StudioDocumentsFolderName: 'Studio 2024'
+      PluginPackedPath : '%AppData%\Trados\Trados Studio\19\Plugins\Packages\'
+      PluginUnpackedPath: '%AppData%\Trados\Trados Studio\19\Plugins\Unpacked\'
+      InstallationFolder: 'C:\Program Files\Trados\Trados Studio\Studio19'
+      DefaultProjectsFolder: 'C:\Users\UserName\Documents\Studio 2026 Release\Projects'
+      StudioDocumentsFolderName: 'Studio 2026 Release'
       AppSigningEmail : app-signing@sdl.com
       ServerProductName: Trados GroupShare 
       ServerProductNameWithVersion: Trados GroupShare 2020 SR1

.github/workflows/update-public-api-documentation.yml

@@ -0,0 +1,236 @@
+name: Update Public API Documentation
+
+
+on:
+  workflow_dispatch:
+    inputs:
+      projectName:
+        description: 'Select the project you want to generate docfx metadata'
+        required: true
+        default: 'TradosStudio'
+        type: choice
+        options:
+          - 'TradosStudio'
+          - 'Terminology'
+      Beta:
+        description: 'Beta version'
+        required: true
+        default: false
+        type: boolean
+      UpdateBranch:
+        description: 'Update Branch'
+        required: true
+        default: false
+        type: boolean
+      projectBranch:
+        description: 'Branch'
+        required: true
+        default: 'master'
+        type: string
+      targetBranch:
+        description: 'Target docfx branch'
+        required: true
+        default: 'main'
+        type: string
+      sourceBranch:
+        description: 'Source docfx branch'
+        required: true
+        default: 'main'
+        type: string
+
+jobs:
+  push_docfx_api_to_github:
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set pipeline ID variable
+        id: set-pipeline-id
+        shell: pwsh
+        run: |
+          $projectName = '${{ inputs.projectName }}'
+          Switch ($projectName) {
+            {$_ -eq "TradosStudio"} { $pipelineID = "1258" }
+            {$_ -eq "Terminology"}  { $pipelineID = "2038" }
+          }
+          Write-Output "projectName: $projectName"
+          Write-Output "pipelineID: $pipelineID"
+          Write-Output "projectBranch: ${{ inputs.projectBranch }}"
+          echo "PIPELINE_ID=$pipelineID" >> $env:GITHUB_ENV
+
+      - name: Download binaries from Azure DevOps
+        shell: pwsh
+        env:
+          AZURE_DEVOPS_TOKEN: ${{ secrets.AZURE_DEVOPS_TOKEN }}
+        run: |
+          $binPath = "${{ github.workspace }}\Bin\Mixed Platforms\Release"
+          New-Item -ItemType Directory -Force -Path $binPath | Out-Null
+
+          $orgUrl    = "https://dev.azure.com/RWS"
+          $project   = "TradosStudio"
+          $pipelineID = $env:PIPELINE_ID
+          $branchName = "refs/heads/${{ inputs.projectBranch }}"
+          $artifactName = "binaries"
+
+          $headers = @{
+            Authorization = "Basic " + [Convert]::ToBase64String(
+              [Text.Encoding]::ASCII.GetBytes(":$env:AZURE_DEVOPS_TOKEN"))
+          }
+
+          # Fetch latest build from the branch (succeeded, partiallySucceeded, or failed)
+          $buildUrl = "$orgUrl/$project/_apis/build/builds" +
+            "?definitions=$pipelineID" +
+            "&branchName=$branchName" +
+            "&tagFilters=retail" +
+            "&resultFilter=succeeded,partiallySucceeded,failed" +
+            "&`$top=1&api-version=7.0"
+
+          $builds = Invoke-RestMethod -Uri $buildUrl -Headers $headers
+          if ($builds.count -eq 0) {
+            Write-Error "No builds found for pipeline $pipelineID on branch $branchName"
+            exit 1
+          }
+
+          $buildId = $builds.value[0].id
+          Write-Host "Using build ID: $buildId"
+
+          # Get artifact download URL
+          $artifactUrl = "$orgUrl/$project/_apis/build/builds/$buildId/artifacts" +
+            "?artifactName=$artifactName&api-version=7.0"
+          $artifact = Invoke-RestMethod -Uri $artifactUrl -Headers $headers
+          $downloadUrl = $artifact.resource.downloadUrl
+          Write-Host "Downloading artifact from: $downloadUrl"
+
+          $zipPath = "${{ github.workspace }}\binaries.zip"
+          Invoke-WebRequest -Uri $downloadUrl -Headers $headers -OutFile $zipPath
+
+          # Extract and copy to target bin path
+          $extractDir = "${{ github.workspace }}\binaries_extracted"
+          Expand-Archive -Path $zipPath -DestinationPath $extractDir -Force
+          # ADO container artifacts unzip into a subfolder named after the artifact
+          $innerDir = Join-Path $extractDir $artifactName
+          $sourceDir = if (Test-Path $innerDir) { $innerDir } else { $extractDir }
+          Copy-Item -Path "$sourceDir\*" -Destination $binPath -Recurse -Force
+          Write-Host "Binaries copied to: $binPath"
+
+      - name: Extract version information from SDL.Versioning.dll
+        shell: pwsh
+        run: |
+          $binPath  = "${{ github.workspace }}\Bin\Mixed Platforms\Release"
+          $dllPath  = Join-Path $binPath "sdl.versioning.dll"
+
+          if (Test-Path $dllPath) {
+            Write-Host "Loading SDL.Versioning.dll from: $dllPath"
+
+            $assembly       = [System.Reflection.Assembly]::LoadFrom($dllPath)
+            $assemblyName   = $assembly.GetName()
+            $version        = $assemblyName.Version
+            $fileVersion    = [System.Diagnostics.FileVersionInfo]::GetVersionInfo($dllPath).FileVersion
+            $productVersion = [System.Diagnostics.FileVersionInfo]::GetVersionInfo($dllPath).ProductVersion
+
+            $metadata = @{
+              AssemblyVersion = $version.ToString()
+              FileVersion     = $fileVersion
+              ProductVersion  = $productVersion
+              FullName        = $assemblyName.FullName
+              Timestamp       = (Get-Item $dllPath).LastWriteTime.ToString("yyyy-MM-dd HH:mm:ss")
+            }
+
+            $versionLabel = if ($productVersion) { $productVersion } else { $version.ToString() }
+            echo "VERSION_LABEL=$versionLabel" >> $env:GITHUB_ENV
+
+            $metadataJson = $metadata | ConvertTo-Json -Depth 10
+            $metadataPath = Join-Path $binPath "source-version-metadata.json"
+            $metadataJson | Out-File -FilePath $metadataPath -Encoding UTF8
+
+            Write-Host "Version metadata written to: $metadataPath"
+            Write-Host "Assembly Version: $($metadata.AssemblyVersion)"
+            Write-Host "File Version:     $($metadata.FileVersion)"
+            Write-Host "Product Version:  $($metadata.ProductVersion)"
+          } else {
+            Write-Warning "SDL.Versioning.dll not found at: $dllPath"
+          }
+
+      - name: Generate API documentation
+        shell: pwsh
+        run: |
+          dotnet tool update -g docfx
+          $projectName  = '${{ inputs.projectName }}'
+          $docfxJsonPath = "docfx_project\$projectName\docfx.json"
+          docfx $docfxJsonPath
+
+      - name: Update the API documentation branch
+        if: ${{ inputs.UpdateBranch == true }}
+        shell: pwsh
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+        run: |
+          $projectName = '${{ inputs.projectName }}'
+          $isBeta      = '${{ inputs.Beta }}'
+
+          Switch ($projectName) {
+            {$_ -eq "TradosStudio"} { $repoName = "studio-api-docs" }
+            {$_ -eq "Terminology"}  { $repoName = "multiterm-api-docs" }
+          }
+
+          if ($isBeta -eq 'true') {
+            $repoName = $repoName + "-beta"
+          }
+
+          $repoURL      = "https://RWS:$env:GH_TOKEN@github.com/RWS/" + $repoName + ".git"
+          $featureBranch = '${{ inputs.targetBranch }}'
+          $sourceBranch  = '${{ inputs.sourceBranch }}'
+          $metadataPath  = "${{ github.workspace }}\Bin\Mixed Platforms\Release\source-version-metadata.json"
+          $prTitle       = "Update generated documentation"
+
+          if (Test-Path $metadataPath) {
+            try {
+              $metadata = Get-Content -Path $metadataPath -Raw | ConvertFrom-Json
+              if ($metadata.ProductVersion) {
+                $prTitle = "Update generated documentation ($($metadata.ProductVersion))"
+              } elseif ($metadata.AssemblyVersion) {
+                $prTitle = "Update generated documentation ($($metadata.AssemblyVersion))"
+              }
+            } catch {
+              Write-Warning "Failed to read version metadata from $metadataPath"
+            }
+          } else {
+            Write-Warning "Version metadata file not found at: $metadataPath"
+          }
+
+          git clone $repoURL
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.sdl.com"
+
+          Set-Location $repoName
+          git checkout $sourceBranch
+
+          $git_response = git ls-remote --heads "$repoURL" "$featureBranch"
+
+          if ($null -eq $git_response) {
+            git checkout -b $featureBranch
+          } else {
+            git checkout -b "temp_$featureBranch"
+          }
+
+          git rm -r .\api\*
+          Copy-Item -Path "..\docfx_project\$projectName\api\" -Destination .\ -Force -Recurse
+
+          if (Test-Path $metadataPath) {
+            Copy-Item -Path $metadataPath -Destination .\source-version-metadata.json -Force
+          }
+
+          git add .\api\*.*
+          if (Test-Path .\source-version-metadata.json) {
+            git add .\source-version-metadata.json
+          }
+
+          git commit -a -m "update api doc"
+          git push $repoURL
+
+          if ($null -ne $git_response) {
+            gh pr create --title $prTitle --body "Update generated documentation" `
+              -H "temp_$featureBranch" -B $featureBranch
+          }
+

writing_guidelines.md → .github/writing_guidelines.md

@@ -12,7 +12,7 @@ Here's a short example for active voice:
 > The cat sat on the mat.
 
 * actor: The cat
-* verd: sat 
+* verb: sat 
 * target: the mat
 
 Here's a short example for passive voice: 

Plugins/TradosStudioDocsPlugin/TradosStudioDocsPlugin/TradosStudioDocsPlugin.csproj

@@ -23,8 +23,8 @@
 
 
 	<ItemGroup>
-		<PackageReference Include="Docfx.Plugins" Version="2.78.3" />
-		<PackageReference Include="Docfx.Common" Version="2.78.3" />
+		<PackageReference Include="Docfx.Plugins" Version="2.78.5" />
+		<PackageReference Include="Docfx.Common" Version="2.78.5" />
 		<PackageReference Include="System.Composition" Version="9.0.3" />
 	</ItemGroup>
 

api/batchtasks/.manifest

@@ -4,8 +4,8 @@
   "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.#ctor": "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.yml",
   "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.Cancel(System.Boolean)": "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.yml",
   "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.ConfigureConverter(Sdl.ProjectAutomation.Core.ProjectFile,Sdl.FileTypeSupport.Framework.IntegrationApi.IMultiFileConverter)": "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.yml",
-  "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.CreateReport(System.String,System.String,System.String)": "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.yml",
   "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.CreateReport(System.String,System.String,System.String,Sdl.ProjectAutomation.AutomaticTasks.LanguageDirection)": "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.yml",
+  "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.CreateReport(System.String,System.String,System.String,System.String)": "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.yml",
   "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.GetSetting``1": "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.yml",
   "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.GetWordCounter(Sdl.ProjectAutomation.Core.ProjectFile)": "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.yml",
   "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.OnFileComplete(Sdl.ProjectAutomation.Core.ProjectFile,Sdl.FileTypeSupport.Framework.IntegrationApi.IMultiFileConverter)": "Sdl.ProjectAutomation.AutomaticTasks.AbstractFileContentProcessingAutomaticTask.yml",