[Xamarin.Android.Build.Tasks] Improve XA1011 error wording (#4779)

Context: https://developercommunity.visualstudio.com/content/problem/1043110/xamarin-androidlinktool-dx.html

Seeing the localized version of the message for XA1011 in context from
a real user's build made @brendanzagaeski realize that the original
wording he wrote for that message was problematic.

One issue was that messages for Xamarin.Android build errors are not
currently accompanied by their numbered error codes when they appear in
the Error List in Visual Studio.  This means that users who see a
localized translation for a message will likely search online using the
localized text instead of the numbered code and will have a more
challenging time finding corresponding release notes and documentation
pages.

Another problem was that the error message used "`$(AndroidLinkTool)`"
as a kind of abbreviation for "the `AndroidLinkTool` MSBuild property".
The idea was that `$(AndroidLinkTool)` matched the MSBuild syntax for
retrieving a property value and would therefore indicate that
`AndroidLinkTool` was an MSBuild property, but Xamarin.Android users
don't typically need to interact too much with MSBuild syntax, so they
wouldn't necessarily recognize the meaning of the abbreviation.  On top
of that, in user projects, `AndroidLinkTool` would be more likely to
appear in an XML tag like `<AndroidLinkTool>` than in a property
retrieval like `$(AndroidLinkTool)`, so the use of `$(AndroidLinkTool)`
in the error message could potentially cause some confusion.

To help address these problems, adjust the wording of the XA1011 error.
In addition to replacing "`$(AndroidLinkTool)`" with "`AndroidLinkTool`
MSBuild property", make the message more actionable by adding
information about how to change the corresponding code shrinker setting
in the Visual Studio project property pages.

[A number of the messages from the dotnet/sdk repo][0] use similar
wording to refer to MSBuild properties.  One difference is that those
messages say "property" instead of "MSBuild property."  @brendanzagaeski
prefers "MSBuild property" because he believes it will help prevent
ambiguity, especially in the localized translations.

TODO: Audit all of the other errors and warnings that currently use the
`$()` syntax, and make similar changes as appropriate.

[0]: https://github.com/dotnet/sdk/blob/1ce8d7029b267c335bf606c591a97bfb9824ece1/src/Tasks/Common/Resources/Strings.resx

Documentation/guides/messages/README.md

@@ -81,7 +81,7 @@ ms.date: 01/24/2020
 + [XA1008](xa1008.md): The TargetFrameworkVersion (Android API level {compileSdk}) is lower than the targetSdkVersion ({targetSdk}).
 + [XA1009](xa1009.md): The {assembly} is Obsolete. Please upgrade to {assembly} {version}
 + [XA1010](xa1010.md): Invalid \`$(AndroidManifestPlaceholders)\` value for Android manifest placeholders. Please use \`key1=value1;key2=value2\` format. The specified value was: `{placeholders}`
-+ [XA1011](xa1011.md): Using ProGuard with the D8 DEX compiler is no longer supported. Please update \`$(AndroidLinkTool)\` to \`r8\`.
++ [XA1011](xa1011.md): Using ProGuard with the D8 DEX compiler is no longer supported. Please set the code shrinker to \`r8\` in the Visual Studio project property pages or edit the project file in a text editor and set the \`AndroidLinkTool\` MSBuild property to \`r8\`.
 + XA1012: Included layout root element override ID '{id}' is not valid.
 + XA1013: Failed to parse ID of node '{name}' in the layout file '{file}'.
 + XA1014: JAR library references with identical file names but different contents were found: {libraries}. Please remove any conflicting libraries from EmbeddedJar, InputJar and AndroidJavaLibrary.

Documentation/guides/messages/xa1011.md

@@ -1,28 +1,37 @@
 ---
 title: Xamarin.Android error XA1011
 description: XA1011 error code
-ms.date: 04/03/2020
+ms.date: 06/05/2020
 ---
 # Xamarin.Android error XA1011
 
 ## Example messages
 
 ```
-error XA1011: Using ProGuard with the D8 DEX compiler is no longer supported. Please update `$(AndroidLinkTool)` to `r8`.
+error XA1011: Using ProGuard with the D8 DEX compiler is no longer supported. Please set the code shrinker to `r8` in the Visual Studio project property pages or edit the project file in a text editor and set the `AndroidLinkTool` MSBuild property to `r8`.
 ```
 
 ## Issue
 
-The project has `$(AndroidDexTool)` set to `d8` and `$(AndroidLinkTool)` set to
-`ProGuard`.  In the past this configuration was allowed, but now only the R8
-code shrinker is supported for use with the D8 DEX compiler.
+The project is currently configured to use the D8 DEX compiler in combination
+with the ProGuard code shrinker.  In the past, using the ProGuard code shrinker
+with the D8 DEX compiler was allowed, but now, only the R8 code shrinker is
+supported for use with the D8 DEX compiler.
 
 ## Solution
 
-Update the `$(AndroidLinkTool)` MSBuild property to `r8` to select the R8 code
-shrinker.  This property corresponds to the **Code shrinker** setting in the
-Visual Studio project properties pages.
+Set the **Code shrinker** in the Visual Studio project properties pages to
+**r8**, or edit the project file [in Visual Studio][edit-project-files] or
+another text editor and set the `AndroidLinkTool` MSBuild property to `r8`:
+
+```xml
+<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
+  <AndroidLinkTool>r8</AndroidLinkTool>
+</PropertyGroup>
+```
 
 R8 might in some cases produce new build warnings or errors compared to
 ProGuard, so the ProGuard rules for the project might require a few updates to
 resolve any new warnings or errors that appear after this change.
+
+[edit-project-files]: https://docs.microsoft.com/visualstudio/msbuild/visual-studio-integration-msbuild#edit-project-files-in-visual-studio

Documentation/release-notes/reword-xa1011.md

@@ -0,0 +1,7 @@
+#### Application and library build and deployment
+
+- _error XA1011: Using ProGuard with the D8 DEX compiler is no longer supported.
+  Please update \`$(AndroidLinkTool)\` to \`r8\`._ did not mention the
+  corresponding term _code shrinker_ that is used in the Visual Studio project
+  property pages and did not mention that `AndroidLinkTool` is an MSBuild
+  property.

src/Xamarin.Android.Build.Tasks/Properties/Resources.resx

@@ -324,8 +324,8 @@ When it appears in the middle of a sentence, "lint" is not capitalized.
     <comment>The following are literal names and should not be translated: `$(AndroidManifestPlaceholders)`</comment>
   </data>
   <data name="XA1011" xml:space="preserve">
-    <value>Using ProGuard with the D8 DEX compiler is no longer supported. Please update `$(AndroidLinkTool)` to `r8`.</value>
-    <comment>The following are literal names and should not be translated: ProGuard, D8, DEX, `$(AndroidLinkTool)`, `r8`</comment>
+    <value>Using ProGuard with the D8 DEX compiler is no longer supported. Please set the code shrinker to `r8` in the Visual Studio project property pages or edit the project file in a text editor and set the `AndroidLinkTool` MSBuild property to `r8`.</value>
+    <comment>The following are literal names and should not be translated: ProGuard, D8, DEX, `r8`, `AndroidLinkTool`</comment>
   </data>
   <data name="XA1012" xml:space="preserve">
     <value>Included layout root element override ID '{0}' is not valid.</value>

src/Xamarin.Android.Build.Tasks/Properties/xlf/Resources.cs.xlf

@@ -253,9 +253,9 @@ When it appears in the middle of a sentence, "lint" is not capitalized.
         <note>The following are literal names and should not be translated: `$(AndroidManifestPlaceholders)`</note>
       </trans-unit>
       <trans-unit id="XA1011">
-        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please update `$(AndroidLinkTool)` to `r8`.</source>
-        <target state="translated">Použití nástroje ProGuard s kompilátorem D8 DEX se už nepodporuje. Aktualizujte prosím nástroj $(AndroidLinkTool) na R8.</target>
-        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `$(AndroidLinkTool)`, `r8`</note>
+        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please set the code shrinker to `r8` in the Visual Studio project property pages or edit the project file in a text editor and set the `AndroidLinkTool` MSBuild property to `r8`.</source>
+        <target state="needs-review-translation">Použití nástroje ProGuard s kompilátorem D8 DEX se už nepodporuje. Aktualizujte prosím nástroj $(AndroidLinkTool) na R8.</target>
+        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `r8`, `AndroidLinkTool`</note>
       </trans-unit>
       <trans-unit id="XA1012">
         <source>Included layout root element override ID '{0}' is not valid.</source>

src/Xamarin.Android.Build.Tasks/Properties/xlf/Resources.de.xlf

@@ -253,9 +253,9 @@ When it appears in the middle of a sentence, "lint" is not capitalized.
         <note>The following are literal names and should not be translated: `$(AndroidManifestPlaceholders)`</note>
       </trans-unit>
       <trans-unit id="XA1011">
-        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please update `$(AndroidLinkTool)` to `r8`.</source>
-        <target state="translated">Die Verwendung von ProGuard mit dem D8 DEX-Compiler wird nicht mehr unterstützt. Aktualisieren Sie "$(AndroidLinkTool)" auf "r8".</target>
-        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `$(AndroidLinkTool)`, `r8`</note>
+        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please set the code shrinker to `r8` in the Visual Studio project property pages or edit the project file in a text editor and set the `AndroidLinkTool` MSBuild property to `r8`.</source>
+        <target state="needs-review-translation">Die Verwendung von ProGuard mit dem D8 DEX-Compiler wird nicht mehr unterstützt. Aktualisieren Sie "$(AndroidLinkTool)" auf "r8".</target>
+        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `r8`, `AndroidLinkTool`</note>
       </trans-unit>
       <trans-unit id="XA1012">
         <source>Included layout root element override ID '{0}' is not valid.</source>

src/Xamarin.Android.Build.Tasks/Properties/xlf/Resources.es.xlf

@@ -253,9 +253,9 @@ When it appears in the middle of a sentence, "lint" is not capitalized.
         <note>The following are literal names and should not be translated: `$(AndroidManifestPlaceholders)`</note>
       </trans-unit>
       <trans-unit id="XA1011">
-        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please update `$(AndroidLinkTool)` to `r8`.</source>
-        <target state="translated">Ya no se admite el uso de ProGuard con el compilador D8 DEX. Actualice "$(AndroidLinkTool)" a "r8".</target>
-        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `$(AndroidLinkTool)`, `r8`</note>
+        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please set the code shrinker to `r8` in the Visual Studio project property pages or edit the project file in a text editor and set the `AndroidLinkTool` MSBuild property to `r8`.</source>
+        <target state="needs-review-translation">Ya no se admite el uso de ProGuard con el compilador D8 DEX. Actualice "$(AndroidLinkTool)" a "r8".</target>
+        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `r8`, `AndroidLinkTool`</note>
       </trans-unit>
       <trans-unit id="XA1012">
         <source>Included layout root element override ID '{0}' is not valid.</source>

src/Xamarin.Android.Build.Tasks/Properties/xlf/Resources.fr.xlf

@@ -253,9 +253,9 @@ When it appears in the middle of a sentence, "lint" is not capitalized.
         <note>The following are literal names and should not be translated: `$(AndroidManifestPlaceholders)`</note>
       </trans-unit>
       <trans-unit id="XA1011">
-        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please update `$(AndroidLinkTool)` to `r8`.</source>
-        <target state="translated">L'utilisation de ProGuard avec le compilateur D8 DEX n'est plus prise en charge. Mettez à jour '$(AndroidLinkTool)' vers 'r8'.</target>
-        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `$(AndroidLinkTool)`, `r8`</note>
+        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please set the code shrinker to `r8` in the Visual Studio project property pages or edit the project file in a text editor and set the `AndroidLinkTool` MSBuild property to `r8`.</source>
+        <target state="needs-review-translation">L'utilisation de ProGuard avec le compilateur D8 DEX n'est plus prise en charge. Mettez à jour '$(AndroidLinkTool)' vers 'r8'.</target>
+        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `r8`, `AndroidLinkTool`</note>
       </trans-unit>
       <trans-unit id="XA1012">
         <source>Included layout root element override ID '{0}' is not valid.</source>

src/Xamarin.Android.Build.Tasks/Properties/xlf/Resources.it.xlf

@@ -253,9 +253,9 @@ When it appears in the middle of a sentence, "lint" is not capitalized.
         <note>The following are literal names and should not be translated: `$(AndroidManifestPlaceholders)`</note>
       </trans-unit>
       <trans-unit id="XA1011">
-        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please update `$(AndroidLinkTool)` to `r8`.</source>
-        <target state="translated">L'utilizzo di ProGuard con il compilatore DEX D8 non è più supportato. Aggiornare `$(AndroidLinkTool)` a `r8`.</target>
-        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `$(AndroidLinkTool)`, `r8`</note>
+        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please set the code shrinker to `r8` in the Visual Studio project property pages or edit the project file in a text editor and set the `AndroidLinkTool` MSBuild property to `r8`.</source>
+        <target state="needs-review-translation">L'utilizzo di ProGuard con il compilatore DEX D8 non è più supportato. Aggiornare `$(AndroidLinkTool)` a `r8`.</target>
+        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `r8`, `AndroidLinkTool`</note>
       </trans-unit>
       <trans-unit id="XA1012">
         <source>Included layout root element override ID '{0}' is not valid.</source>

src/Xamarin.Android.Build.Tasks/Properties/xlf/Resources.ja.xlf

@@ -253,9 +253,9 @@ When it appears in the middle of a sentence, "lint" is not capitalized.
         <note>The following are literal names and should not be translated: `$(AndroidManifestPlaceholders)`</note>
       </trans-unit>
       <trans-unit id="XA1011">
-        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please update `$(AndroidLinkTool)` to `r8`.</source>
-        <target state="translated">D8 DEX コンパイラで ProGuard を使用することはサポートされなくなりました。'$(AndroidLinkTool)' を 'r8' に更新してください。</target>
-        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `$(AndroidLinkTool)`, `r8`</note>
+        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please set the code shrinker to `r8` in the Visual Studio project property pages or edit the project file in a text editor and set the `AndroidLinkTool` MSBuild property to `r8`.</source>
+        <target state="needs-review-translation">D8 DEX コンパイラで ProGuard を使用することはサポートされなくなりました。'$(AndroidLinkTool)' を 'r8' に更新してください。</target>
+        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `r8`, `AndroidLinkTool`</note>
       </trans-unit>
       <trans-unit id="XA1012">
         <source>Included layout root element override ID '{0}' is not valid.</source>

src/Xamarin.Android.Build.Tasks/Properties/xlf/Resources.ko.xlf

@@ -253,9 +253,9 @@ When it appears in the middle of a sentence, "lint" is not capitalized.
         <note>The following are literal names and should not be translated: `$(AndroidManifestPlaceholders)`</note>
       </trans-unit>
       <trans-unit id="XA1011">
-        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please update `$(AndroidLinkTool)` to `r8`.</source>
-        <target state="translated">D8 DEX 컴파일러와 함께 ProGuard 사용이 더 이상 지원되지 않습니다. `$(AndroidLinkTool)`을 `r8`로 업데이트하세요.</target>
-        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `$(AndroidLinkTool)`, `r8`</note>
+        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please set the code shrinker to `r8` in the Visual Studio project property pages or edit the project file in a text editor and set the `AndroidLinkTool` MSBuild property to `r8`.</source>
+        <target state="needs-review-translation">D8 DEX 컴파일러와 함께 ProGuard 사용이 더 이상 지원되지 않습니다. `$(AndroidLinkTool)`을 `r8`로 업데이트하세요.</target>
+        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `r8`, `AndroidLinkTool`</note>
       </trans-unit>
       <trans-unit id="XA1012">
         <source>Included layout root element override ID '{0}' is not valid.</source>

src/Xamarin.Android.Build.Tasks/Properties/xlf/Resources.pl.xlf

@@ -253,9 +253,9 @@ When it appears in the middle of a sentence, "lint" is not capitalized.
         <note>The following are literal names and should not be translated: `$(AndroidManifestPlaceholders)`</note>
       </trans-unit>
       <trans-unit id="XA1011">
-        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please update `$(AndroidLinkTool)` to `r8`.</source>
-        <target state="translated">Używanie narzędzie ProGuard z kompilatorem D8 DEX nie jest już obsługiwane. Zaktualizuj narzędzie „$(AndroidLinkTool)” do wersji „R8”.</target>
-        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `$(AndroidLinkTool)`, `r8`</note>
+        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please set the code shrinker to `r8` in the Visual Studio project property pages or edit the project file in a text editor and set the `AndroidLinkTool` MSBuild property to `r8`.</source>
+        <target state="needs-review-translation">Używanie narzędzie ProGuard z kompilatorem D8 DEX nie jest już obsługiwane. Zaktualizuj narzędzie „$(AndroidLinkTool)” do wersji „R8”.</target>
+        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `r8`, `AndroidLinkTool`</note>
       </trans-unit>
       <trans-unit id="XA1012">
         <source>Included layout root element override ID '{0}' is not valid.</source>

src/Xamarin.Android.Build.Tasks/Properties/xlf/Resources.pt-BR.xlf

@@ -253,9 +253,9 @@ When it appears in the middle of a sentence, "lint" is not capitalized.
         <note>The following are literal names and should not be translated: `$(AndroidManifestPlaceholders)`</note>
       </trans-unit>
       <trans-unit id="XA1011">
-        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please update `$(AndroidLinkTool)` to `r8`.</source>
-        <target state="translated">Não há mais suporte para o uso do ProGuard com o compilador de DEX do D8. Atualize o `$(AndroidLinkTool)` para `r8`.</target>
-        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `$(AndroidLinkTool)`, `r8`</note>
+        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please set the code shrinker to `r8` in the Visual Studio project property pages or edit the project file in a text editor and set the `AndroidLinkTool` MSBuild property to `r8`.</source>
+        <target state="needs-review-translation">Não há mais suporte para o uso do ProGuard com o compilador de DEX do D8. Atualize o `$(AndroidLinkTool)` para `r8`.</target>
+        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `r8`, `AndroidLinkTool`</note>
       </trans-unit>
       <trans-unit id="XA1012">
         <source>Included layout root element override ID '{0}' is not valid.</source>

src/Xamarin.Android.Build.Tasks/Properties/xlf/Resources.ru.xlf

@@ -253,9 +253,9 @@ When it appears in the middle of a sentence, "lint" is not capitalized.
         <note>The following are literal names and should not be translated: `$(AndroidManifestPlaceholders)`</note>
       </trans-unit>
       <trans-unit id="XA1011">
-        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please update `$(AndroidLinkTool)` to `r8`.</source>
-        <target state="translated">Использование ProGuard с компилятором D8 DEX больше не поддерживается. Обновите "$(AndroidLinkTool)" до версии "r8".</target>
-        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `$(AndroidLinkTool)`, `r8`</note>
+        <source>Using ProGuard with the D8 DEX compiler is no longer supported. Please set the code shrinker to `r8` in the Visual Studio project property pages or edit the project file in a text editor and set the `AndroidLinkTool` MSBuild property to `r8`.</source>
+        <target state="needs-review-translation">Использование ProGuard с компилятором D8 DEX больше не поддерживается. Обновите "$(AndroidLinkTool)" до версии "r8".</target>
+        <note>The following are literal names and should not be translated: ProGuard, D8, DEX, `r8`, `AndroidLinkTool`</note>
       </trans-unit>
       <trans-unit id="XA1012">
         <source>Included layout root element override ID '{0}' is not valid.</source>