URLOptions - LanguageEmbedding

Link Manager GetItemURL 

Features -

1. Usage - Sitecore.Links.LinkManager.GetItemUrl(item)

2. How its rendered is controlled by a setting in site config -

   <linkManager defaultProvider="sitecore">
     <providers>
       <clear />
       <add name="sitecore" type="Sitecore.Links.LinkProvider, Sitecore.Kernel" addAspxExtension="true" alwaysIncludeServerUrl="false" encodeNames="true" languageEmbedding="asNeeded" languageLocation="filePath" shortenUrls="true" useDisplayName="false" />
     </providers>
   </linkManager>

3. out-of-box Options 

   addAspxExtension: false | true (If you set this to false,
   remember to configure IIS to map all requests (*) to ASP.NET)
      alwaysIncludeServerUrl: false | true
      encodeNames: true | false
      languageEmbedding: asNeeded | always | never
      languageLocation: filePath | queryString
      lowercaseUrls: true | false
      shortenUrls: true | false
      useDisplayName: false | true

4. LanguageEmbedding
   1. Always - sample url - http://<site-name>/en/some-page-url
   2. Never - sample url - http://<site-name>/some-page-url
   3. asNeeded - As defined "Sitecore includes the language in the URL if it cannot determine the context site from the incoming HTTP request, if that HTTP request does not include a cookie that specifies a language, or if the language of the linked item differs from the context language.".Since its vague, if you have to use this setting for LanguageEmbedding, then use your tenant site definition to set it to "Always" or "Never". Ref - Sitecore Dynamic link doc.pdf
   4. Note - if you set it to "Never" and your site is Multi-lingual, SEO will not like it as you will have same links for multiple language versions of the same page. 
5. Workaround - 

   1. Custom Link provider - Inherit class from Sitecore.Links.LinkProvider and override the GetItemUrl(...) method. 

      namespace Custom
      {
         public class CustomLinkProvider : Sitecore.Links.LinkProvider
         {
            public override string GetItemUrl(Sitecore.Data.Items.Item item,
               Sitecore.Links.UrlOptions options)
            {
               if (/* my condition of when to create custom url */)
               {
                  /*generate and return custom url*/
                  return CustomUrlManager.GetCustomUrl(item);
               }
               /*else return the default url generated by Sitecore*/
               return base.GetItemUrl(item, options);
            }
         }
      }

   2. Update default Link provider 

       <linkManager defaultProvider="custom">
         <providers>
            <clear />
            <add name="custom" type="Custom.CustomLinkProvider, Custom" addAspxExtension="true"
               alwaysIncludeServerUrl="false" encodeNames="true" languageEmbedding="always" languageLocation="filePath"
               shortenUrls="true" useDisplayName="false" />
            <add name="sitecore" type="Sitecore.Links.LinkProvider, Sitecore.Kernel" addAspxExtension="true"
               alwaysIncludeServerUrl="false" encodeNames="true" languageEmbedding="never" languageLocation="filePath"
               shortenUrls="true" useDisplayName="false" />
         </providers>
      </linkManager>